Webhooks

qué es un webbook un webhook es un mecanismo mediante el cual gire será capaz de notificar mediante http post a su servidor cuando una transacción sea realizada o cambie de estado, así usted podrá tomar las acciones necesarias en su sistema al efecto de reflejar el nuevo estado de una operación servicios que soportan webhooks checkout ordenes de pago suscripciones datos especiales checkout checkout agregará al final del objeto "data" un nodo con tu información personalizada, tal como el id de checkout subscription el módulo de suscripciones agregará información sobre la suscripción, suscriptor y ejecución al final del objeto "data" órdenes de pago el módulo ordenes de pago no agrega datos adicionales consideraciones especiales para poder utilizar el servicio de webhooks, la plataforma destino debera soportar cifrado tls 1 2 en adelante, no debiendo soportar las versiones 1 1 y anteriores ejemplo de contenido enviado en un webhook simple headers content type application/json ejemplo de contenido enviado en un webhook simple pago con código de barra { "type" "checkout", "data" { "result" true, "view" { "type" "cash", "options" { "barcode" true } }, "payment" { "id" "xcnaq5ddo", "description" "venta de producto", "operation" { "type" "payment v2" }, "status" { "code" "2", "text" "en espera", "message" "el cupón vence en 24hs " }, "total" 1333, "currency" { "code" "test", "text" "test money", "symbol" "t$" }, "riskanalysis" { "band" "n/a", "level" "n/a" }, "created" "2020 12 04t00 08 45 604z", "updated" "2020 12 04t00 08 46 154z", "reference" "29", "source" { "name" "gire/gire", "type" "cash", "reference" "arg gire cash", "barcode" "044715261462012050133300000000000000000000515003571363", "url" "https //utils gire com/barcode/044715261462012050133300000000000000000000515003571363?bcid=interleaved2of5\&includetext=1\&textxalign=center\&textsize=11" } }, "entity" { "name" "wayne inc", "uid" "iambatman" }, "customer" { "uid" "12123123", "name" "juan perez wayne", "phone" "12123123", "identification" "110303456", "email" "soybatman\@wayneinc com" }, "user" { "name" "juan perez wayne", "email" "soybatman\@wayneinc com" }, "source" { "name" "gire/gire", "type" "cash", "reference" "arg gire cash" }, "checkout" { "uid" "tk0l70hee9m4t6ebph" } } } ejemplo de contenido enviado en un webhook de checkout { "data" { "checkout" { "currency" "ars", "total" 145170, "uid" "chk\ uouiowam3nu1be19wb" }, "customer" { "email" "iam\@batman com", "identification" "12123123", "name" "bruce wayne", "phone" "+541122334455", "uid" "48186e4f 8bda 4d0f 95e1 430d89a187ef" }, "entity" { "name" "demo s a ", "uid" "123lrvrto" }, "ipaddress" "192 228 17 57", "payment" { "created" "2024 04 16t23 04 40 523z", "currency" { "code" "ars", "locale" "es ar", "symbol" "$", "text" "peso argentino" }, "description" "orden 11111111111", "id" "3z6d9yf71l0lggrr8drt3w", "operation" { "type" "payment v2" }, "reference" "1111111111", "requestedcurrency" { "code" "ars", "locale" "es ar", "symbol" "$", "text" "peso argentino" }, "requestedtotal" 145170, "riskanalysis" { "band" "n/a", "level" "n/a" }, "source" { "cardholder" { "identification" "12123123", "name" "bruce wayne" }, "expiration" { "month" "06", "year" "24" }, "installment" { "amount" 145170, "count" 1, "description" "1 cuota", "reference" "1", "tags" \[], "uid" "nzqwp58ga" }, "name" "visa banco santander", "number" "46600000 4601", "reference" "visa santanderrio", "transaction" { "authorizationcode" "004288", "batchno" "", "resultcode" "0", "retrievalreferenceno" "410723133668", "ticketno" "", "transactionid" "3z6d9yf71l0lggrr8drt3w" }, "type" "card", "variant" "credit" }, "status" { "code" "200", "data" {}, "message" "transacción aprobada", "resultcode" "0", "text" "aprobado", "view" "default" }, "total" 145170, "updated" "2024 04 16t23 04 42 146z" }, "result" true, "source" { "name" "visa banco santander", "reference" "visa santanderrio", "type" "card" }, "user" { "email" "iam\@batman com", "name" "bruce wayne" }, "view" { "type" "card" } }, "type" "checkout" } ejemplo de contenido enviado en un webhook de checkout con items tipo suscripción { "type" "checkout", "data" { "result" true, "view" { "type" "card" }, "payment" { "id" "abc1234", "description" "mi descripción", "operation" { "type" "payment v2" }, "status" { "code" "200", "text" "aprobado", "message" "transacción aprobada" }, "total" 1564 33, "currency" { "code" "ars", "text" "peso argentino", "symbol" "$" }, "riskanalysis" { "band" "red", "level" 7 1 }, "created" "2020 12 04t21 27 26 348z", "updated" "2020 12 04t21 27 28 280z", "reference" "external reference", "source" { "cardholder" { "identification" "12123123", "name" "demo" }, "expiration" { "month" "12", "year" "34" }, "installment" { "amount" 10, "count" 1, "description" "débito", "reference" "1" }, "name" "visa débito", "number" "450799 0010", "reference" "visa debit", "transaction" { "authorizationcode" "462515385471", "batchno" "", "resultcode" "0", "retrievalreferenceno" "", "ticketno" "258570348489", "transactionid" "chd e0ecycai5ei5dxra6k" }, "type" "card" } }, "entity" { "name" "wayne inc", "uid" "iambatman" }, "customer" { "uid" "12123123", "name" "juan perez wayne", "phone" "12123123", "identification" "110303456", "email" "soybatman\@wayneinc com" }, "source" { "name" "visa", "type" "card", "reference" "visa" }, "checkout" { "uid" "tk0l70hee9m4t6ebph", "total" 140 00, "currency" "ars" }, "subscriptions" \[ { "subscription" "uid subscription", "subscriber" "uid subscriber" } ] } } ejemplo de contenido enviado en un webhook de suscripciones { "type" "subscription\ execution", "data" { "result" true, "view" { "type" "card" }, "payment" { "id" "abc1234", "description" "mi descripción", "operation" { "type" "payment v2" }, "status" { "code" "200", "text" "aprobado", "message" "transacción aprobada" }, "total" 1564 33, "currency" { "code" "ars", "text" "peso argentino", "symbol" "$" }, "riskanalysis" { "band" "red", "level" 7 1 }, "created" "2020 12 04t21 27 26 348z", "updated" "2020 12 04t21 27 28 280z", "reference" "external reference", "source" { "cardholder" { "identification" "12123123", "name" "demo" }, "expiration" { "month" "12", "year" "34" }, "installment" { "amount" 10, "count" 1, "description" "débito", "reference" "1" }, "name" "visa débito", "number" "450799 0010", "reference" "visa debit", "transaction" { "authorizationcode" "462515385471", "batchno" "", "resultcode" "0", "retrievalreferenceno" "", "ticketno" "258570348489", "transactionid" "chd e0ecycai5ei5dxra6k" }, "type" "card" } }, "entity" { "name" "wayne inc", "uid" "iambatman" }, "customer" { "uid" "12123123", "name" "juan perez wayne", "phone" "12123123", "identification" "110303456", "email" "soybatman\@wayneinc com" }, "source" { "name" "visa", "type" "card", "reference" "visa" }, "subscription" { "uid" "cba33333", "interval" "1m", "limit" 0, "name" "el nombre de mi suscripción", "description" "la descripción de mi suscripción", "reference" "my reference", "total" 1564 33 }, "subscriber" { "uid" "off1233", "reference" "my ref", "period" 4, "customer" { "name" "juan perez wayne", "phone" "12123123", "identification" "110303456", "email" "soybatman\@wayneinc com" } }, "execution" { "uid" "rbcnxgntj8n2jv4r63" } } } webhooks especiales tipo de operatoria split split distribuído split híbrido multicard multi vendor en estos casos adicionalmente a la información standard enviada en un webhook se enviarán las transacciones hijas de la operación principal bajo el campo "childs" { "data" { "checkout" { "currency" "ars", "total" 10, "uid" "chk 42dq1hjt7zgu6o38jq" }, "childs" \[ { "entity" { "name" "mi ready", "uid" "myready" }, "payment" { "id" "chd e0ecycai5ei5dxra6k", "source" { "cardholder" { "identification" "12123123", "name" "demo" }, "expiration" { "month" "12", "year" "34" }, "installment" { "amount" 10, "count" 1, "description" "débito", "reference" "1" }, "name" "visa débito", "number" "450799 0010", "reference" "visa debit", "transaction" { "authorizationcode" "462515385471", "batchno" "", "resultcode" "0", "retrievalreferenceno" "", "ticketno" "258570348489", "transactionid" "chd e0ecycai5ei5dxra6k" }, "type" "card" }, "status" { "code" "200", "data" {}, "message" "transacción aprobada", "resultcode" "0", "text" "aprobado", "view" "default" }, "total" 10 }, "source" { "name" "visa débito", "reference" "visa debit", "type" "card" }, "view" { "type" "card" } } ], "customer" { "email" "demo\@gire com", "identification" "12123123", "name" "demo gire" }, "entity" { "name" "mi ready", "uid" "myready" }, "payment" { "created" "2023 01 06t00 25 49 358z", "currency" { "code" "test", "locale" "es", "symbol" "t$", "text" "test money" }, "description" "descripción de la venta", "id" "gequu3v5afnfn28dp73esd", "operation" { "type" "payment multiple sources" }, "reference" "ref test multicheckout 9", "riskanalysis" { "band" "n/a", "level" "n/a" }, "source" { "cardholder" {}, "expiration" { "month" "", "year" "" }, "installment" { "amount" 0, "count" 1, "description" "1", "reference" "" }, "name" "multicard", "number" "", "reference" "multicard", "transaction" { "authorizationcode" "", "batchno" "", "resultcode" "", "retrievalreferenceno" "", "ticketno" "", "transactionid" "gequu3v5afnfn28dp73esd" }, "type" "card" }, "status" { "code" "200", "data" {}, "message" "transacción aprobada", "resultcode" 1, "text" "aprobado", "view" "default" }, "total" 10, "updated" "2023 01 06t00 26 26 681z" }, "result" true, "source" { "name" "multicard", "reference" "multicard", "type" "card" }, "user" { "email" "demo\@gire com", "name" "demo gire" }, "view" { "type" "card" } }, "type" "checkout" } bloqueo permanente de url no recepción de webhook un mensaje de bloqueo con el formato blocked\ hard block (http 404 permanent block http 404) significa que nuestro sistema dejó de enviar webhooks a esa url porque el endpoint respondió con http 404 – not found este código indica que el servidor de destino no encontró ningún recurso en la dirección o ruta indicada dado que el 404 se interpreta como que la ruta no existe, el bloqueo se establece de forma permanente hasta que el problema sea corregido del lado del subcomercio pasos a seguir ante un bloqueo ante este tipo de bloqueo, solicitamos al subcomercio revisar los siguientes puntos en su infraestructura verificar la url registrada confirmar que la url configurada para recibir los webhooks sea exactamente la correcta, sin errores de tipeo ni versiones desactualizadas de la ruta (por ejemplo, /webhooks/v1/ en lugar de /webhooks/v2/ ) confirmar que el endpoint esté activo validar que el endpoint se encuentre desplegado y en funcionamiento, y que no haya sido eliminado, renombrado o migrado a otro dominio o servicio en un despliegue reciente revisar la traza (trace) de la solicitud verificar en la infraestructura propia (apm, tracing distribuido o logs de acceso) si la petición del webhook llegó efectivamente al servidor o aplicación si la traza muestra que la solicitud nunca llegó , el problema puede originarse antes del servidor (dns, balanceador, firewall perimetral, o dominio caído) si la traza muestra que la solicitud sí llegó pero no fue enrutada a ningún handler, se confirma que la ruta específica no está correctamente mapeada en la aplicación — este es el escenario más habitual en un error 404 este análisis permite identificar con precisión en qué punto se está "perdiendo" la petición, en lugar de limitarse a observar si el endpoint responde o no revisar logs de infraestructura consultar los logs del servidor web, api gateway, balanceador o proxy (nginx, apache, kong, aws api gateway, etc ) para confirmar si la petición llegó y cuál fue la ruta exacta solicitada confirmar el método http verificar que el método utilizado coincida con el esperado (normalmente post ) un mal ruteo en el gateway también puede devolver 404 si la ruta no está mapeada para ese verbo revisar redirecciones o cambios de dominio/ssl si existe una redirección (301/302) hacia otra url y esta no está correctamente configurada, la solicitud puede terminar devolviendo 404 probar el endpoint manualmente realizar una prueba con curl o postman simulando el envío de un webhook, para confirmar que la ruta responde correctamente (200 ok) y ya no devuelve 404 recomendación realizar esta prueba replicando el mismo formato de payload y los mismos headers que utiliza el webhook real, de manera que la validación sea representativa del comportamiento en producción