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
Ejemplo de Contenido WebHook de Checkout con código 200:
{
"data": {
"checkout": {
"currency": "ARS",
"total": 200,
"uid": "CHK:E8F3MM2OHGU3DEMO"
},
"customer": {
"email": "[email protected]",
"identification": "999999",
"name": "DEMO FRANCO",
"phone": "999999999,
"uid": "00000"
},
"entity": {
"name": "DEMO",
"uid": "J83WS4NZXOTDEMO"
},
"ipAddress": "00.00.00",
"payment": {
"created": "2026-10-20T12:51:07.261Z",
"currency": {
"code": "ARS",
"exponent": 2,
"locale": "es-AR",
"symbol": "$",
"text": "Peso Argentino"
},
"description": "DEMO",
"id": "DGOC5WT3E18ILNPDEMO",
"operation": {
"type": "payment.v2"
},
"reference": "db8000214cda913352fdfeDEMO",
"requestedCurrency": {
"code": "ARS",
"exponent": 2,
"locale": "es-AR",
"symbol": "$",
"text": "Peso Argentino"
},
"requestedTotal": 200,
"riskAnalysis": {
"band": "N/A",
"level": "N/A"
},
"source": {
"cardholder": {
"identification": "99999999",
"name": "DEMO DEMO"
},
"detectedReference": "visa.galicia",
"expiration": {
"month": "11",
"year": "31"
},
"installment": {
"amount": 200,
"count": 1,
"description": "1 cuota",
"reference": "1",
"tags": [],
"uid": "JQXDXY6OHADEMO"
},
"name": "Visa",
"number": "45999999****9999",
"reference": "visa",
"transaction": {
"acquirer": "arg.prisma",
"authorizationCode": "99999",
"batchNo": "999",
"merchantNo": "9999999",
"resultCode": "00",
"retrievalReferenceNo": "9999999",
"ticketNo": "5473",
"transactionId": "DGOC5WT3E18DEMO"
},
"type": "card",
"variant": "credit"
},
"status": {
"code": "200",
"data": {},
"message": "Transacción Aprobada",
"resultCode": "00",
"text": "Aprobado",
"view": "default"
},
"total": 200,
"updated": "2026-10-20T12:51:09.037Z"
},
"result": true,
"source": {
"name": "Visa",
"reference": "visa",
"type": "card"
},
"view": {
"type": "card"
}
},
"type": "checkout"
}Ejemplo de Contenido WebHook de Checkout con código 300:
{
"data": {
"checkout": {
"currency": "ARS",
"total": 200,
"uid": "CHK:MXBQ7L1SOTDEMO"
},
"customer": {
"email": "[email protected]",
"identification": "999999999",
"name": "DEMO",
"phone": "999999999",
"uid": "9999"
},
"entity": {
"name": "DEMO DEMO",
"uid": "J83WS4NZXOTITDEMO"
},
"ipAddress": "99.99.99",
"payment": {
"created": "2026-10-15T17:56:57.042Z",
"currency": {
"code": "ARS",
"exponent": 2,
"locale": "es-AR",
"symbol": "$",
"text": "Peso Argentino"
},
"description": "DEMO DEMO",
"id": "YPGS3G2QW9347DEMO",
"operation": {
"type": "payment.v2"
},
"reference": "2477118933b420eDEMO",
"requestedCurrency": {
"code": "ARS",
"exponent": 2,
"locale": "es-AR",
"symbol": "$",
"text": "Peso Argentino"
},
"requestedTotal": 200,
"riskAnalysis": {
"band": "N/A",
"level": "N/A"
},
"source": {
"cardholder": {
"identification": "99999999",
"name": "DEMO DEMO"
},
"detectedReference": "visa.debit.bancoprovinciabsas",
"expiration": {
"month": "06",
"year": "28"
},
"installment": {
"amount": 200,
"count": 1,
"description": "Débito",
"reference": "1",
"tags": [],
"uid": "EYKDMB1E2DEMO"
},
"name": "Visa Débito",
"number": "43989999****9999",
"reference": "visa.debit",
"transaction": {
"acquirer": "arg.prisma",
"authorizationCode": "999999",
"batchNo": "134",
"merchantNo": "999999",
"resultCode": "00",
"retrievalReferenceNo": "0000000099999",
"ticketNo": "9999",
"transactionId": "YPGS3G2QW93476DDEMO"
},
"type": "card",
"variant": "debit"
},
"status": {
"code": "300",
"data": {},
"message": "Transacción Aprobada",
"resultCode": "00",
"text": "Acreditado",
"view": "default"
},
"total": 200,
"updated": "2026-10-19T09:00:14.842Z"
},
"result": true,
"source": {
"name": "Visa Débito",
"reference": "visa.debit",
"type": "card"
},
"view": {
"type": "card"
}
},
"type": "checkout"
}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": "[email protected]",
"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": "[email protected]",
"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.