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.

Set up webhooks

To set up a new webhook:

In your Belvo dashboard, go to the payment webhooks section.
In the Open Payments Webhooks tab, click +New webhook.
Fill in the New webhook form with the required information.
- URL: the URL to receive the webhook notifications.
- Authorization: an optional bearer token to use if your URL is protected.
Click Create 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)

Client-side webhook response best practice

We highly recommend that once you receive a webhook you reply to Belvo with a 2XX status code within five seconds to confirm that you have received the webhook. Otherwise, our API will retry the request.

Webhook retry policy

If our system does not receive 2XX status code, it automatically tries to send the request again. This retry process will happen up to three times, with each attempt spaced 60 seconds apart. For example, if the first attempt fails, our system waits for 60 seconds before trying again and will continue this pattern until it either receives a successful response or reaches the maximum of three retries.