A webhook is a web callback that Belvo uses to send notifications regarding your payments.

Setting up your webhooks

To set up your webhook URL:

1. Log in to your Direct Debit Portal. (Sandbox Login | Production Login)
2. Go to Developers -> Webhooks. (Sandbox Webhooks | Production Webhooks)
3. Enter your URL.
4. Click Set.

✅ You're webhook URL is successfully added.

Webhook events

{
  "eventType": "payment_request_update", // API resource event type
  "eventCode": "payment_request_successful", // Webhook event code
  "datetime": "2022-01-01T12:34:56.789Z", // The ISO-8601 timestamp when the event was sent.
  "details": {
    "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5", // Object ID of the API resource.
    "reference": "your_reference_here", // Optional description of the object
    "status": "failed", // The status of the resource
    "failedReason": "BANK_CODE", // If status=failed, a failure code
    "failedMessage": "A description of the error" // If status=failed, a description of the failure.
  }
}

📘

failedReason and failedMessage fields

For details regarding the expected failedReason and failedMessage (including the list of possible values), please see our Direct Debit Error guide.

For information about specific payloads for a given API resource and webhook code, just click on the webhook Event Code in the table below.

Best Practices

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.

Retry policy

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.