A webhook is a web callback that Belvo uses to send notifications about a specific link. You will need to set up webhooks in order to use Belvo's APIs.
To set up your webhook URL:
- Log in to your Direct Debit Portal. (Sandbox Login | Production Login)
- Go to Developers -> Webhooks. (Sandbox Webhooks | Production Webhooks)
- Enter your URL.
- Click Set.
✅ Your webhook URL is successfully added.
{
"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
}
}| Parameter | Type | Description |
|---|---|---|
eventType | string | The type of the API resource event. Can be one of: customer_update, payment_method_update, or payment_request_update. |
eventCode | string | The code of the webhook event. For details regarding the possible values, please see the Webhook Event Codes section below. |
datetime | string | The ISO-8601 timestamp when the event was sent. |
details | object | An object containing specific data about the event. |
details.id | string | The Belvo ID of the API resource (Customer, Payment Method, or Payment Request) that the event is related to. |
details.reference | string | If you provided a reference when creating the resource, an optional description of the object. |
details.status | string | The status of the resource. |
details.amount | number | The amount of the payment request. This field is present for all payment_request event codes. |
| string | If the status is For details regarding the expected |
| string | If the status is For details regarding the expected |
details.documentNumber | string | If the event is related to a customer, this field contains the RFC or CURP of the customer related to the direct debit payment method. This field is only available for customer-related events. |
For information about specific payloads for a given API resource and webhook code, just click on the webhook Event Code in the table below.
| Resource | Event Type | Event Code | Sent whenever... |
|---|---|---|---|
| Customers | customer_update | customer_blocked | the customer related to the direct debit payment method was blocked due to suspicious activity. This webhook is sent globally to all merchants, even if they don't have the blocked customer registered, since the block list is shared across all merchants. |
| Customers | customer_update | customer_unblocked | the customer related to the direct debit payment method was unblocked after review by relevant parties. |
| Payment Methods | payment_method_update | payment_method_registration_successful | the registration of the direct debit payment method was successful. |
| Payment Methods | payment_method_update | payment_method_registration_failed | the registration of the direct debit payment method failed. |
| Payment Methods | payment_method_update | payment_method_registration_canceled | the direct debit registration was canceled (usually by the owner). |
| Payment Requests | payment_request_update | payment_request_successful | the payout was successful and we received confirmation from the payment infrastructure provider. |
| Payment Requests | payment_request_update | payment_request_failed | an error is reported by the payment infrastructure provider. |
| Payment Requests | payment_request_update | payment_request_chargeback | a chargeback has been made by your customer. |
When a customer is blocked due to a chargeback, all merchants receive the customer_blocked webhook, regardless of whether they have that customer registered. This is because Belvo maintains a global block list shared across all merchants to protect the entire ecosystem from fraudulent activity.
The webhook payload includes the blocked customer's documentNumber (RFC or CURP) so you can check if the customer exists in your system and take appropriate action.
The customer_blocked webhook is sent only once to each merchant (in other words, if you already received one and a new chargeback occurs for the same customer but for another merchant, you will not receive another webhook for that customer).
When you receive a webhook from Belvo, make sure that you respond with a 2XX status code (for example, a 200). If Belvo's system does not receive a 200 response from your server, we will automatically retry to send the request. For more detailed, please see our Retry policy section.
When Belvo does not receive a 2XX response from your server, we retry sending the webhook every 60 minutes for up to 10 attempts.
For example, if the first (initial) attempt fails, our system waits for 60 minutes before trying again and will continue this pattern until it either receives a successful response or reaches the maximum of 10 retries.