Payment Webhooks (Mexico)

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

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.

Setting up your webhooks

To set up a webhook:

1. Log in to your Direct Debit Portal. (Sandbox Login | Production Login)
2. Go to Developers -> Webhooks. (Sandbox Webhooks | Production Webhooks)
3. Click New webhook.
4. Enter your URL.
5. Select the events you want to receive, or select All events.
6. Optionally, enter an authentication token. See Authentication.
7. Click Create webhook.

✅ Your webhook is successfully added.

You can add up to 5 webhooks. To edit a webhook, click its row in the list. Use the Active / Inactive toggle to pause or resume deliveries to a webhook without deleting it, and the delete icon to remove it. Inactive webhooks do not receive any events.

Multiple webhooks

Each event is delivered to every active webhook that is subscribed to its eventType (or to All events). Every webhook receives the same payload.

If two webhooks are subscribed to the same event, both receive it. This is intentional, so you can send the same events to different systems, such as your backend and a monitoring tool.

Authentication

Each webhook can have its own authentication token. When a token is set, every request to that webhook includes it in the Authorization header:

Authorization: Bearer <token>

Verify this header on your server to make sure the request comes from Belvo.

Test your webhook

To check that your webhook is reachable, click Test on the webhook's row and select an event type. The list shows the event types the webhook is subscribed to (all of them if it is subscribed to All events). Belvo sends a sample payload for the selected event type to your URL.

The Event delivery panel shows the request that was sent, along with the response code and body returned by your server. Click Resend to send it again. Test deliveries are not retried.

Webhook Payload

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

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

Webhook Event Codes

The Event Type column is what you subscribe to when you set up a webhook.

Consent rejection reasons

When a consent moves to rejected or incomplete_information because of its files, the webhook includes details.reasons. It has one item for each file that failed validation, with the fileType and a code that explains the problem. If one file has several problems, we send the main one.

{
  "eventType": "consent_update",
  "eventCode": "consent_incomplete_information",
  "datetime": "2025-10-30T12:34:56.789Z",
  "details": {
    "id": "4fa8f2b1-3c7d-4e9a-b5c6-111111111101",
    "paymentMethodId": "4fa8f2b1-3c7d-4e9a-b5c6-111111111102",
    "status": "incomplete_information",
    "reasons": [
      { "fileType": "id_front", "code": "duplicate_file" },
      { "fileType": "id_back", "code": "duplicate_file" },
      { "fileType": "selfie", "code": "duplicate_file" },
      { "fileType": "contract", "code": "duplicate_file" }
    ]
  }
}

Best Practices

When you receive a webhook from Belvo, make sure that you respond with a 2XX status code (for example, a 200). See our Retry policy for which failures we retry.

Retry policy

We retry a webhook delivery only when your server is unreachable, times out, or responds with an HTTP 5xx status code. In those cases we retry every 60 minutes for up to 3 attempts (the initial delivery plus 2 retries).

We do not retry HTTP 4xx responses (for example 400, 404, or 418). Those are treated as client errors and the webhook is not sent again.

For example, if the first attempt fails with a 503, our system waits 60 minutes before trying again, and continues until it receives a 2XX response or reaches the maximum of 2 retries.

Retries are per webhook. If one of your webhooks fails, only that webhook is retried. Your other webhooks are not affected.