Webhooks (Payments)
Check out how to set up a webhooks for our payment initiation solution!
A webhook is a web callback that Belvo uses to send notifications about a specific link.
This article is about webhooks for our Payment Initiation solution. For information regarding our Aggregation and Enrichment webhooks, check out this article.
Register a webhook
To register a webhook, you need to make the following POST request to Register a new payment webhook with the following information:
{
"name": "Your webhook name",
"url": "Your webhook URL",
"auth_header": "Authorization",
"auth_token": "Bearer hv7alD71j0dzXf09iKfg7u"
}
Where:
name
is the name you want to provide to identify the webhookurl
is the URL where the webhook should be sent to.auth_header
is the authentication header for the request. Must be set toAuthorization
.auth_token
is the authentication token you need to send webhook events. Can be either:Bearer
and a token (for Bearer authentication).Basic
and a base64-encoded username:password string (for Basic authentication).
Once you register a webhook, you will receive the following response:
{
"id": "3b9a69f7-0f0a-455b-832d-49ad6fd4905c",
"name": "Your webhook name",
"url": "Your webhook URL",
"auth_header": "Authorization",
"auth_token": "*******",
"created_at": "2022-02-09T08:45:50.406032Z",
"created_by": "c232d66c-90cd-4aca-a32d-5c2e7f7799ba"
}
Where:
Response Parameter | Description |
---|---|
id | Belvo's unique ID for the webhook. |
name | The name you provided to identify the webhook. |
url | The URL you provided to send webhook information to. |
auth_header | The authentication header for the request. |
auth_token | The authentication token you need to send webhook events. |
created_at | Timestamp of when the webhook was created in our database. |
created_by | Belvo's unique ID of the user that created the webhook. |
Webhook types
All webhook events come with a core payload (as described in the code example below).
{
"webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999", // Belvo webhook ID
"webhook_type": "TRANSACTIONS", // From what endpoint the webhook is from
"webhook_code": "STATUS_UPDATE", // Webhook type
"object_id": "16f68516-bcbc-4cf7-b815-c500d4204e28", // The id of the object created
"data": {
// Contents of the webhook. For more information, please see the relative Webhook type documentation.
}
}
For information about the data specific to a given webhook, just click on the webhook type in the table below.
Type | Event | Sent whenever... | Product |
---|---|---|---|
BANK_ACCOUNTS | OBJECT_CREATED | There is a new bank account created. | - 🇨🇴 Colombia (PSE) |
PAYMENT_INTENTS | STATUS_UPDATE | There is an update on the status of a payment intent. | - 🇧🇷 Brazil (OFPI) - 🇨🇴 Colombia (PSE) |
TRANSACTIONS | OBJECT_CREATED | There is a new transaction created. | - 🇧🇷 Brazil (OFPI) - 🇨🇴 Colombia (PSE) |
Updated 4 months ago