Webhooks

🚧 Webhook Sandbox

En este momento, la funcionalidad de webhooks en el ambiente de sandbox se encuentra en desarrollo y, por lo tanto, no está disponible para todos los usuarios.

¿Qué son los webhooks?

Los webhooks son recursos para intercambiar información entre dos sistemas en el momento de un evento con mensajes HTTP. Pueden usarse para automatizar tareas al suscribirse a eventos de productos, que notifican a tu integración. En el Área de Desarrollador, puedes acceder a los webhooks de cada aplicación.

Webhook endpoint

El endpoint de webhook es la dirección usada por tu integración para ser notificada de los eventos a los que se suscribe. El endpoint debe cumplir con algunos requisitos:

Estar en conformidad con el protocolo https;
No estar acompañado de puertos personalizados. Nuestro servidor realizará solicitudes únicamente al puerto estándar del protocolo https.

POST https://example.com/notifications

Eventos

Los eventos de webhook son las notificaciones enviadas por el producto sobre algún proceso que está ocurriendo.

Un evento de webhook contiene esta estructura:

Atributo	Tipo	Descripción
webhookId	guid	Id del webhook que recibe la notificación.
event	string	Tipo del evento notificado.
data	objeto	Objeto con datos asociados al evento. La estructura del objeto se define por el tipo de evento notificado.

En este ejemplo, el objeto data se define por el tipo de evento transactions.debit, indicando un débito en la cuenta digital.

{
    "webhookId": "bb2ae4c5-8094-4f3c-b0e0-02646ba6e5e3",
    "event": "transactions.debit",
    "data": {
        //payload del webhook
    }
}

x-correlation-id

El webhook llegará con el campo x-correlation-id en el header. El valor del x-correlation-id es el mismo en cada nuevo intento.

Recibiendo webhooks

Al configurar un endpoint, recibirás notificaciones para los tipos de evento elegidos. La suscripción será determinada por la forma en que los recibes y respondes vía status HTTP.

Status Code	Descripción	Acción
200	Éxito	Webhook entregado.
4XX	Falla en el envío	Indica que nuestro agent fue bloqueado por tu servidor al intentar realizar el envío. Continúa al protocolo de reintento.
5XX	Servidor cliente no disponible	Indica que tu servidor no está disponible para nuestro agent. Continúa al protocolo de reintento

*La aplicación tiene 10 segundos para responder un webhook antes de que el mensaje falle.

Consentimiento

Por cuestiones de seguridad, tu endpoint recibirá únicamente los eventos referentes a los alcances de producto que formaron parte de un flujo de generación de token de tu aplicación. Por ejemplo, en caso de que tu aplicación tenga un webhook con los eventos de saldo y extracto suscritos, pero nunca haya realizado el flujo de generación con estos tokens, el agent no enviará estos eventos a tu endpoint.

Así, en caso de que no estés recibiendo un evento al que estás suscrito, asegúrate de realizar el flujo de generación de token con el alcance referente al producto que emite el evento.

Protocolo de reintento

El protocolo de reintento es una forma de asegurar que inestabilidades puntuales en tu sistema no impidan la recepción de webhooks.

Al obtener un status code de la familia 4XX o 5XX, nuestro agent intentará el reenvío del webhook tres veces más dentro de 10 minutos. En caso de no obtener éxito, el status code obtenido en el último intento será asociado al intento de envío que quedará disponible en el panel de gestión de webhooks, pudiendo ser reprocesado manualmente por el usuario.

Ejemplo de mensaje de webhook

POST /notifications HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer ba143409-d498-4ac4-a6ae-b97d44a19e3f
//El header authorization se completa con su webhook secret

{
    "webhookId": "bb2ae4c5-8094-4f3c-b0e0-02646ba6e5e3",
    "event": "transactions.debit",
    "data": {
        "accountId": "37297902000141-208-50-003886850",
        "date": "2022-03-02T22:01:55.274Z",
        "creditDebitIndicator": "DEBIT",
        "amount": 30900,
        "currency": "BRL",
        "transactionId": "33449743"
    }
}

Nuevos intentos

Tras un error, el webhook llegará con el campo correlation-id con un código que no cambiará.

¿Qué son los webhooks?​

Webhook endpoint​

Eventos​

x-correlation-id​

Recibiendo webhooks​

Consentimiento​

Protocolo de reintento​

Tags​

Ejemplo de mensaje de webhook​

Nuevos intentos​