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

Where:

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.