Webhooks

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 -> API Keys. (Sandbox Webhooks | Production Webhooks)
3. Enter your URL.
4. Click Set.

✅ You're webhook URL is successfully added.

Webhook events

Core webhook payload

{
  "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.
  }
}

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 Code	Sent whenever...
Payment Methods	payment_method_registration_successful	the registration of the direct debit payment method was successful.
Payment Methods	payment_method_registration_failed	the registration of the direct debit payment method failed.
Payment Methods	payment_method_registration_canceled	the direct debit registration was canceled (usually by the owner).
Payment Requests	payment_request_successful	the payout was successful and we received confirmation from the payment infrastructure provider.
Payment Requests	payment_request_failed	an error is reported by the payment infrastructure provider.
Payment Requests	payment_request_chargeback	a chargeback has been made by your customer.

Retry policy

If our system does not receive 2XX status code, it automatically tries to send the request again. This retry process will happen up to 10 times, with each attempt spaced 60 minutes apart. For example, if the first 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.