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 https://api.belvo.com/payments/webhooks/:

curl --location --request POST 'https://api.belvo.com/payments/webhooks/' \
--header 'Authorization: Basic YOUR_SECRETKEY_AND_PASSWORD' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "Your webhook name", 
  "url": "Your webhook URL"
}'

Where:

name is the name you want to provide to identify the webhook
url is the URL where the webhook should be sent to.

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",
  "created_at": "2021-11-04T20:18:02Z",
  "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
`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)