Create a new webhook configuration to receive reminders of a payment.
Allows you to receive automatic notifications via webhook -prior registration of a valid URL by the customer- for billers that allow balance inquiry, being activated only after a successful payment and being valid only during the month following the payment (if the bill is not paid within that period no notification is sent for the next month). Shipments are scheduled based on the payment date plus one month minus 5, 3 and 1 day (not based on the original due date), and in case of delivery failure up to 3 retries with increasing delays are made; if the bill is paid before any of the shipments, the remaining reminders are cancelled.
POST /api/v2/webhooks
Registers a new webhook URL. When an event is triggered, the system will send a signed HTTP POST request to the configured URL. The request will include a secret signature for validation.
Bearer Authentication
| Name | Type | Required | Description |
|---|---|---|---|
| Content-Type | string | Yes | Must be application/json |
| Authorization | string | Yes | Bearer token |
{
"url": "https://your-api.com/webhooks"
}{
"id": 1,
"url": "https://your-api.com/webhooks",
"secret": "6e5a9465cb8e117cfe63473ba7310ec96898db7c893a967b35cf58d669e47337"
}| Field | Type | Description |
|---|---|---|
| id | integer | Unique identifier for the webhook configuration |
| url | string | The webhook URL that was registered |
| secret | string | A secret key used for signing requests in the X-Signature header |
| Name | Type | Description |
|---|---|---|
| Content-Type | string | application/json |
| X-Signature | string | Hex-encoded HMAC-SHA256 signature of the payload |
| X-Timestamp | string | Unix timestamp when the request was generated |
{
id: "439bc073-1b68-4a91-bcbb-08ed60bfa542",
company_name: "CFE",
account_reference: "123456789012",
amount: 100.20,
due_date: "2025-02-20",
last_payment_date: "2025-01-20"
}| Field | Type | Description |
|---|---|---|
| id | integer | Unique identifier for the webhook reminder |
| company_name | string | Name of the company |
| account_reference | string | Account reference of the billed service |
| amount | decimal | Current balance of the billed account |
| due_date | string/null | Due date of the billed account |
| last_payment_date | string | Date of the last payment of this account |
Webhook payloads are signed using HMAC-SHA256 to ensure authenticity. Each webhook request includes the following headers:
| Header | Description |
|---|---|
| X-Signature | Hex-encoded HMAC-SHA256 signature of the payload |
| X-Timestamp | Unix timestamp when the request was generated |
To ensure the integrity of the notification, you should verify the signature of the X-Signature header in this way:
timestamp = headers['X-Timestamp']
signature = headers['X-Signature']
payload = timestamp + "." + request_body
expected_signature = sign('SHA256', secret, payload)
expected_signature == signatureYour server must return HTTP 202 Accepted to acknowledge the reception of the webhook.
Any other response status will be treated as a failed delivery and may trigger retries. If the reception of the webhook notification fails, three attempts will be made during the same day, the first after 5 minutes, the second after 10 minutes and the third after 30 minutes.