# Payment Webhooks (Mexico)

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 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**.


✅ Your webhook URL is successfully added.

## Webhook Payload

Webhook Payload Example (Success)

```json Webhook Payload Example (Success)
{
  "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
  }
}
```

Webhook Payload Example (Failure)

```json Webhook Payload Example (Failure)
{
  "eventType": "payment_request_update",
  "eventCode": "payment_request_failed",
  "datetime": "2022-01-01T12:34:56.789Z",
  "details": {
    "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5",
    "reference": "your_reference_here",
    "status": "failed",
    "amount": 100.5,
    "failedReason": "01",
    "failedMessage": "Cuenta inexistente"
  }
}
```

Webhook Payload Example (Customer)

```json Webhook Payload Example (Customer)
{
  "eventType": "customer_update",
  "eventCode": "customer_blocked",
  "datetime": "2022-01-01T12:34:56.789Z",
  "details": {
    "documentNumber": "RFC/CURP of Customer"
  }
}
```

| 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. |
| `details.failedReason`
 | string
 | If the status is `failed`, this field contains a failure code. This field is `null` if the `status` is not `failed`.
For details regarding the expected `failedReason` and `failedMessage` (including the list of possible values), please see our Direct Debit Bank Errors guide.
 |
| `details.failedMessage`
 | string
 | If the status is `failed`, this field contains a description of the failure. This field is `null` if the `status` is not `failed`.
For details regarding the expected `failedReason` and `failedMessage` (including the list of possible values), please see our Direct Debit Bank Errors guide.
 |
| `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.

## Webhook Event Codes

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


Global Customer Blocking Notifications
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).

## 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.