📘

In this section, you will learn how to setup webhooks and what events you can receive.

Belvo is providing a set of webhooks to help you build a more proactive and immersive experience for your customers.

A webhook is a web callback that Belvo can use to send notification events specific to a link, for example when new transactions are available or when the credentials are not working anymore.

❗️

The webhooks are only working along with recurrent links.

You can learn more about recurrent links in our dedicated guide.

How webhooks work with recurrent links?

Recurrent links are refreshed automatically, by Belvo, on a daily basis to retrieve:

• For bank institutions:
  • the accounts information of the link, including the live balance and credit data
  • the new transactions added during the last 365 days
  • the owners personal information of the link
• For fiscal institutions:
  • the new invoices sent or received during the last 5 years
  • the new tax return added during the last 5 years

While we automatically refresh a link, we can notify your application whenever interesting events occurred. For example, we can notify you when new transactions are available, the link credentials changed, etc...

After defining a webhook URL for your account, Belvo will send a POST payload with a raw JSON to this URL for each event. The content of this JSON will depend on the event.

How to setup your webhook URL?

You can setup your webhooks from your dashboard.
Go to the "Configuration" section of the dashboard and the "Webhooks" sub-section.
Fill the form to add a new webhook:

• URL: the URL to receive the webhook notifications
• Authorization: an optional bearer token we will use in the request if your URL is protected

👍

Webhook configuration for Sandbox

The webhook URLs in the dashboard are for production only. If you want to test the webhooks in sandbox, send us your test URL at [email protected] and we will do the configuration for you.

Your webhook is now setup and your application will be notified for new events related to your recurrent links.

📘

Webhook retrials

If Belvo does not receive a 2xx HTTP status code, the notification attempt is repeated 5 times using exponential backoff to allow recovering from server malfunctions.

Available webhook events

We currently support the following events:

Accounts webhooks

New accounts available

You can receive notifications via a webhook whenever new accounts are available for a bank recurrent link.

Payload example:

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "ACCOUNTS",
  "webhook_code": "new_accounts_available",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "data": {
    "new_accounts": 1
  }
}

Once you receive the webhook notification, you can perform a search using the list of accounts to pull instantly the details of those new accounts. For example:

curl https://api.belvo.co/api/accounts/ \
  -u [Secret Key ID]:[Secret Key PASSWORD]

Historical update

As soon as your banking recurrent link is created, we will asynchronously load the accounts available. You can receive notifications via a webhook whenever the account list is available for you to access.

Payload example:

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "ACCOUNTS",
  "webhook_code": "historical_update",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "data": {
    "total_accounts": 5
  }
}

Transactions webhooks

New transactions available

You can receive notifications via a webhook whenever new transactions are available for a bank recurrent link.
Payload example:

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "TRANSACTIONS",
  "webhook_code": "new_transactions_available",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "data": {
    "new_transactions": 19
  }
}

We define new_transactions as all new transactions found in the institution for this link.
It could be the new transactions from the last 24 hours but also new transactions added by the institution for previous days.
After creating a new recurrent link, all history of transactions will be pulled during the next refresh and the new_transactions will include all this initial history.

Once you receive the webhook notification, you can perform a search using the list of transactions to pull instantly the details of those new transactions. For example:

curl --request GET 'https://api.belvo.co/api/transactions/?link=16f68516-bcbc-4cf7-b815-c500d4204e28&collected_at__range=2020-01-01,2020-01-02' \
-u [Secret Key ID]:[Secret Key PASSWORD]

Historical update

As soon as your banking recurrent link is created, we will asynchronously load the maximum number of transactions allowed by the institution. You can receive notifications via a webhook whenever the history of transactions is available for you to access.

Payload example:

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "TRANSACTIONS",
  "webhook_code": "historical_update",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "data": {
    "total_transactions": 19,
    "total_inflow_transactions": 10,
    "total_outflow_transactions": 9,
    "first_transaction_date": "2017-01-03",
    "last_transaction_date": "2020-03-25"
  }
}

Once you receive the webhook notification, you can perform a search using the list of transactions to pull instantly the details of those historical transactions. For example:

curl --request GET 'https://api.belvo.co/api/transactions/?value_date__range=2020-08-01,2020-08-17' \
-u [Secret Key ID]:[Secret Key PASSWORD]

Owners webhooks

New owners available

You can receive notifications via a webhook whenever new owners are available for a bank recurrent link.

Payload example:

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "OWNERS",
  "webhook_code": "new_owners_available",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "data": {
    "new_owners": 1
  }
}

Once you receive the webhook notification, you can perform a search using the list of owners to pull instantly the details of those new owners. For example:

curl https://api.belvo.co/api/owners/ \
  -u [Secret Key ID]:[Secret Key PASSWORD]

Historical update

As soon as your banking recurrent link is created, we will asynchronously load the owners available. You can receive notifications via a webhook whenever the owner list is available for you to access.

Payload example:

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "OWNERS",
  "webhook_code": "historical_update",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "data": {
    "total_owners": 2
  }
}

 Links webhooks

Invalid credentials

You can receive notifications via a webhook whenever credentials are not valid anymore to update a recurrent link (e.g.when a user changes its bank credentials).
Payload example:

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "LINK",
  "webhook_code": "invalid_credentials",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "data": {
    "error_code": "login_error",
    "error_message": "Invalid credentials provided to login to the institution",
    "status": 400
  }
}

Once you receive this notification, you can ask your customer to update their new password and then perform a link update to save the new password. The recurrent link will then be refreshed during the next cycle. For example:

curl -X PUT https://api.belvo.co/api/links/{id} \
  -H 'Content-Type: application/json' \
  -H 'Host: api.belvo.co' \
  -H 'cache-control: no-cache' \
  -d '{
      "password": "newpassword"
  }' \
  -u [Secret Key ID]:[Secret Key PASSWORD]

Token required

You can receive notifications via a webhook whenever we need a new MFA token, requested by the institution, to keep the recurrent link working.

Payload example:

{
  "webhook_type": "LINK",
  "webhook_code": "token_required",
  "link_id": "30cb4806-6e00-48a4-91c9-ca55968576c8",
  "data": {
    "error_code": "token_required",
    "error_message": "MFA token was required by the institution",
    "status": 428,
    "session": "2675b703b9d4451f8d4861a3eee54449",
    "expiry": 9600,
    "token_generation_data": {
      "instructions": "Use this code to generate the token",
      "type": "numeric",
      "value": "12345"
    }
  }
}

Once you receive this notification, you can ask your customer for a new token and then perform a link patch, to resume the link register session that was paused. The recurrent link will then be refreshed during the next cycle.

Link patch example:

curl -X PATCH \
  https://api.belvo.co/api/links/ \
  -H 'Content-Type: application/json' \
  -H 'Host: api.belvo.co' \
  -H 'cache-control: no-cache' \
  -d '{
      "session": "2675b703b9d4451f8d4861a3eee54449",
      "token": "123456",
      "link": "30cb4806-6e00-48a4-91c9-ca55968576c8"
  }' \
  -u [Secret Key ID]:[Secret Key PASSWORD]

 Invoices webhooks

Historical updates

As soon as your fiscal recurrent link is created, we will asynchronously load the last 5 years of invoices history. You can receive notifications via a webhook whenever the history of invoices is available for you to access.
We send two events:

• historical_inflow_update: when the last 5 years of inflow invoices are available
• historical_outflow_update: when the last 5 years of outflow invoices are available

Inflow payload example:

{
   "webhook_id":"ccc9c589bfcb44bc99ce749229ccf142",
   "webhook_type":"INVOICES",
   "webhook_code":"historical_inflow_update",
   "link_id":"2f5d361d-dad6-45d4-a0bf-26d479766067",
   "data":{
      "total_invoices":5333,
      "first_invoice_date":"2017-07-31",
      "last_invoice_date":"2020-07-28"
   }
}

Outflow payload example:

{
   "webhook_id":"1ac2917cb25f4e38af9260c0782d3408",
   "webhook_type":"INVOICES",
   "webhook_code":"historical_outflow_update",
   "link_id":"2f5d361d-dad6-45d4-a0bf-26d479766067",
   "data":{
      "total_invoices":1000,
      "first_invoice_date":"2015-07-31",
      "last_invoice_date":"2019-10-30"
   }
}

Once you receive the webhook notification, you can perform a search using the list of invoices to pull instantly the details of those historical invoices. For example:

curl --request GET 'https://api.belvo.co/api/invoices/?link=2f5d361d-dad6-45d4-a0bf-26d479766067' \
-u [Secret Key ID]:[Secret Key PASSWORD]

New invoices available

After the historical update, you can receive notifications via a webhook whenever new invoices are available for a fiscal recurrent link.

Payload example:

{
   "webhook_id":"09d4b9826d0a4050903719fac218a276",
   "webhook_type":"INVOICES",
   "webhook_code":"new_invoices_available",
   "link_id":"331ba983-0cfa-4186-93fc-936f3946cca3",
   "data":{
      "new_invoices":10,
      "new_inflow_invoices":5,
      "new_outflow_invoices":5
   }
}

We define new invoices as all new invoices found in the institution for this link.
It could be the new invoices from the last 24 hours but also invoices added by the institution for previous days.

Once you receive the webhook notification, you can perform a search using the list of invoices to pull instantly the details of those new invoices. For example:

# all new invoices
curl --request GET 'https://api.belvo.co/api/invoices/?link=331ba983-0cfa-4186-93fc-936f3946cca3&collected_at__range=2020-01-01,2020-01-02' \
-u [Secret Key ID]:[Secret Key PASSWORD]

# all new INFLOW invoices
curl --request GET 'https://api.belvo.co/api/invoices/?link=331ba983-0cfa-4186-93fc-936f3946cca3&collected_at__range=2020-01-01,2020-01-02&type=INFLOW' \
-u [Secret Key ID]:[Secret Key PASSWORD]

# all new OUTFLOW invoices
curl --request GET 'https://api.belvo.co/api/invoices/?link=331ba983-0cfa-4186-93fc-936f3946cca3&collected_at__range=2020-01-01,2020-01-02&type=OUTFLOW' \
-u [Secret Key ID]:[Secret Key PASSWORD]

Cancelled invoices

After the historical update, you can receive notifications via a webhook whenever existing past invoices are cancelled for a fiscal recurrent link.

Payload example:

{
   "webhook_id":"aadf41a1fc8e4f79a49f7f04027ac999",
   "webhook_type":"INVOICES",
   "webhook_code":"invoices_cancelled",
   "link_id":"16f68516-bcbc-4cf7-b815-c500d4204e28",
   "data":{
      "cancelled_invoices":[
         "0a362860-c92f-4414-a731-a772e88ab54b",
         "0a376126-c23r-2131-b745-a876d77cd76c"
      ]
   }
}

We define canceled invoices as all existing invoices with a new "cancelled" status in the institution for this link.

Once you receive the webhook notification, you can access directly the invoice using the Details of invoices to pull instantly the details of those canceled invoices. For example:

# cancelled invoice
curl --request GET 'https://api.belvo.co/api/invoices/0a362860-c92f-4414-a731-a772e88ab54b/' \
-u [Secret Key ID]:[Secret Key PASSWORD]

 Tax returns webhooks

Historical update

As soon as your fiscal recurrent link is created, we will asynchronously load the last 5 years of tax returns history. You can receive notifications via a webhook whenever the history is available for you to access.

Payload example:

{
   "webhook_id":"80fa38b7cad34950b210626abd86bfe9",
   "webhook_type":"TAX_RETURNS",
   "webhook_code":"historical_update",
   "link_id":"2f5d361d-dad6-45d4-a0bf-26d479766067",
   "data":{
      "total_tax_returns":2,
      "first_tax_return_year":2017,
      "last_tax_return_year":2018
   }
}

Once you receive the webhook notification, you can perform a search using the list of tax returns to pull instantly the details of those historical tax returns. For example:

curl --request GET 'https://api.belvo.co/api/tax-returns/?link=2f5d361d-dad6-45d4-a0bf-26d479766067' \
-u [Secret Key ID]:[Secret Key PASSWORD]

New tax returns available

After the historical update, you can receive notifications via a webhook whenever new tax returns are available for a fiscal recurrent link.

Payload example:

{
   "webhook_id":"351610c401e34e728900495fda5b970a",
   "webhook_type":"TAX_RETURNS",
   "webhook_code":"new_tax_returns_available",
   "link_id":"331ba983-0cfa-4186-93fc-936f3946cca3",
   "data":{
      "new_tax_returns":1
   }
}

We define new tax returns as all new tax returns found in the institution for this link.
It could be the new tax returns from the last year but also tax returns added by the institution for previous years.

Once you receive the webhook notification, you can perform a search using the list of tax returns to pull instantly the details of those new tax returns. For example:

curl --request GET 'https://api.belvo.co/api/tax-returns/?link=331ba983-0cfa-4186-93fc-936f3946cca3&collected_at__range=2020-01-01,2020-01-02' \
-u [Secret Key ID]:[Secret Key PASSWORD]

 Tax status webhook

Historical update

As soon as your fiscal recurrent link is created, we will asynchronously load the last tax status. You can receive notifications via a webhook whenever this document is available for you to access.

Payload example:

{
   "webhook_id":"03d1ca0d62db4f769488265d141047b7",
   "webhook_type":"TAX_STATUS",
   "webhook_code":"historical_update",
   "link_id":"2f5d361d-dad6-45d4-a0bf-26d479766067",
   "data":{
      "total_tax_status":1,
      "last_status_change_date":"1995-08-01"
   }
}

Once you receive the webhook notification, you can perform a search using the list of tax status to pull instantly the details of this document. For example:

curl --request GET 'https://api.belvo.co/api/tax-status/?link=2f5d361d-dad6-45d4-a0bf-26d479766067' \
-u [Secret Key ID]:[Secret Key PASSWORD]

 Webhooks in Sandbox

You can test the webhooks in Sandbox. All events from your sandbox account will be sent to the configured sandbox URL.

👍

Configure your test webhook URL for Sandbox

The webhook URLs in the dashboard are for production only. If you want to test the webhooks in sandbox, send us your test URL at [email protected] and we will do the configuration for you.