# Webhook Notifications

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.

## Endpoint

POST /api/v2/webhooks

## Description

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.

## Authentication

Bearer Authentication

## Request

### Headers

| Name | Type | Required | Description |
|  --- | --- | --- | --- |
| Content-Type | string | Yes | Must be `application/json` |
| Authorization | string | Yes | Bearer token |


### Body


```json
{
  "url": "https://your-api.com/webhooks"
}
```

## Response


```json
{
  "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 |


## Webhook Request

### Headers

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


### Body


```json
{
  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 |


## Signature Verification

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 == signature
```

## Webhook Delivery Expectation

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