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",
"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. |
| 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. |
| 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 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.