Un webhook es una devolución de llamada web que Belvo utiliza para enviar notificaciones sobre un enlace específico. Necesitarás configurar webhooks para poder usar las APIs de Belvo.
Para configurar tu URL de webhook:
- Inicia sesión en tu Portal de Débito Directo. (Inicio de sesión Sandbox | Inicio de sesión Producción)
- Ve a Desarrolladores -> Webhooks. (Webhooks Sandbox | Webhooks Producción)
- Ingresa tu URL.
- Haz clic en Set.
✅ Tu URL de webhook se ha agregado exitosamente.
{
"eventType": "payment_request_update",
"eventCode": "payment_request_successful",
"datetime": "2022-01-01T12:34:56.789Z",
"details": {
"id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5",
"reference": "your_reference_here",
"status": "successful",
"amount": 100.5,
"failedReason": null,
"failedMessage": null
}
}| Parámetro | Tipo | Descripción |
|---|---|---|
eventType | string | El tipo de evento del recurso de la API. Puede ser uno de: customer_update, payment_method_update, o payment_request_update. |
eventCode | string | El código del evento del webhook. Para obtener detalles sobre los posibles valores, consulte la sección Códigos de Evento del Webhook a continuación. |
datetime | string | La marca de tiempo ISO-8601 cuando se envió el evento. |
details | object | Un objeto que contiene datos específicos sobre el evento. |
details.id | string | El ID de Belvo del recurso de la API (Cliente, Método de Pago o Solicitud de Pago) al que está relacionado el evento. |
details.reference | string | Si proporcionó una reference al crear el recurso, una descripción opcional del objeto. |
details.status | string | El estado del recurso. |
details.amount | number | El monto de la solicitud de pago. Este campo está presente para todos los códigos de evento de payment_request. |
| string | Si el estado es Para obtener detalles sobre el |
| string | Si el estado es Para obtener detalles sobre el |
details.documentNumber | string | Si el evento está relacionado con un cliente, este campo contiene el RFC o CURP del cliente relacionado con el método de pago de débito directo. Este campo solo está disponible para eventos relacionados con clientes. |
Para obtener información sobre cargas útiles específicas para un recurso de la API y código de webhook dado, simplemente haga clic en el Código de Evento del webhook en la tabla a continuación.
| Recurso | Tipo de Evento | Código de Evento | Enviado cuando... |
|---|---|---|---|
| Clientes | customer_update | customer_blocked | el cliente relacionado con el método de pago por débito directo fue bloqueado debido a actividad sospechosa. |
| Clientes | customer_update | customer_unblocked | el cliente relacionado con el método de pago por débito directo fue desbloqueado después de la revisión por las partes relevantes. |
| Métodos de Pago | payment_method_update | payment_method_registration_successful | el registro del método de pago por débito directo fue exitoso. |
| Métodos de Pago | payment_method_update | payment_method_registration_failed | el registro del método de pago por débito directo falló. |
| Métodos de Pago | payment_method_update | payment_method_registration_canceled | el registro de débito directo fue cancelado (generalmente por el propietario). |
| Solicitudes de Pago | payment_request_update | payment_request_successful | el pago fue exitoso y recibimos confirmación del proveedor de infraestructura de pago. |
| Solicitudes de Pago | payment_request_update | payment_request_failed | un error es reportado por el proveedor de infraestructura de pago. |
| Solicitudes de Pago | payment_request_update | payment_request_chargeback | se ha realizado un contracargo por parte de su cliente. |
Cuando recibas un webhook de Belvo, asegúrate de responder con un código de estado 2XX (por ejemplo, un 200). Si el sistema de Belvo no recibe una respuesta 200 de tu servidor, automáticamente intentaremos reenviar la solicitud. Para más detalles, consulta nuestra sección de Política de reintento.
Cuando Belvo no recibe una respuesta 2XX de tu servidor, reintentamos enviar el webhook cada 60 minutos hasta un máximo de 10 intentos.
Por ejemplo, si el primer intento (inicial) falla, nuestro sistema espera 60 minutos antes de intentar nuevamente y continuará con este patrón hasta que reciba una respuesta exitosa o alcance el máximo de 10 reintentos.