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: consent_update, customer_update, payment_method_update, o payment_request_update. |
eventCode | string | El código del evento del webhook. Para detalles sobre los valores posibles, por favor consulta la sección de Códigos de Evento de 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 proporcionaste 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 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. |
details.paymentMethodId | string | Si el evento está relacionado con un consentimiento, este campo contiene el ID del método de pago asociado. Este campo solo está disponible para eventos relacionados con consentimientos. |
Para obtener información sobre payloads específicos para un recurso de API y código de webhook dado, 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 | Se envía 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. Este webhook se envía globalmente a todos los comerciantes, incluso si no tienen registrado al cliente bloqueado, ya que la lista de bloqueos se comparte entre todos los comerciantes. |
| 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. |
| Consentimientos | consent_update | consent_submitted | se han cargado todos los documentos requeridos para el consentimiento. |
| Consentimientos | consent_update | consent_confirmed | el consentimiento ha sido aprobado y ahora está activo. |
| Consentimientos | consent_update | consent_incomplete_information | faltan documentos o son inválidos para el consentimiento. |
| Consentimientos | consent_update | consent_rejected | el consentimiento ha sido denegado. |
| 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 del 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 tu cliente. |
Cuando un cliente es bloqueado debido a un contracargo, todos los comerciantes reciben el webhook customer_blocked, independientemente de si tienen registrado a ese cliente. Esto se debe a que Belvo mantiene una lista de bloqueos global compartida entre todos los comerciantes para proteger a todo el ecosistema de actividades fraudulentas.
La carga útil del webhook incluye el documentNumber (RFC o CURP) del cliente bloqueado para que puedas verificar si el cliente existe en tu sistema y tomar las medidas adecuadas.
El webhook customer_blocked se envía solo una vez a cada comerciante (en otras palabras, si ya recibiste uno y ocurre un nuevo contracargo para el mismo cliente pero para otro comerciante, no recibirás otro webhook para ese cliente).
El sistema envía notificaciones de webhook cada vez que cambia el estado de un consentimiento para permitir el seguimiento en tiempo real del ciclo de vida del consentimiento. No se envía un webhook para el estado inicial awaiting_information.
Si está configurado, los webhooks de consentimiento incluyen un encabezado Authorization con el secreto del webhook del comerciante para una verificación segura.
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.