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" 


  • name is the name you want to provide to identify the webhook
  • url is the URL where the webhook should be sent to.
  • auth_header is the authentication header for the request. Must be set to Authorization.
  • 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"


Response ParameterDescription
idBelvo's unique ID for the webhook.
nameThe name you provided to identify the webhook.
urlThe URL you provided to send webhook information to.
auth_headerThe authentication header for the request.
auth_tokenThe authentication token you need to send webhook events.
created_atTimestamp of when the webhook was created in our database.
created_byBelvo'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.

TypeEventSent whenever...Product
BANK_ACCOUNTSOBJECT_CREATEDThere is a new bank account created.- πŸ‡¨πŸ‡΄ Colombia (PSE)
PAYMENT_INTENTSSTATUS_UPDATEThere is an update on the status of a payment intent.- πŸ‡§πŸ‡· Brazil (OFPI)
- πŸ‡¨πŸ‡΄ Colombia (PSE)
TRANSACTIONSOBJECT_CREATEDThere is a new transaction created.- πŸ‡§πŸ‡· Brazil (OFPI)
- πŸ‡¨πŸ‡΄ Colombia (PSE)