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",
"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 detalles sobre los posibles valores, por favor consulta la sección de Códigos de Eventos del Webhook a continuación. |
datetime | string | La marca de tiempo ISO-8601 cuando el evento fue enviado. |
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 el evento está relacionado. |
details.reference | string | Si proporcionaste una reference al crear el recurso, una descripción opcional del objeto. |
details.status | string | El estado del recurso. |
| string | Si el estado es Para detalles sobre el |
| string | Si el estado es Para 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 información sobre payloads específicos para un recurso de la API dado y código de webhook, simplemente haz 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.