Historical update

As soon as a banking recurrent link containing receivables information is created, we asynchronously load the receivable transactions available. You will receive a historical_updatenotification whenever the receivable transactions list is available for you to access.

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "RECEIVABLES_TRANSACTIONS",
  "webhook_code": "historical_update",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_transactions": 19, // Total number of transactions found
    "first_transaction_date": "2017-01-03", // First transaction date
    "last_transaction_date": "2020-03-25" // Last transaction date
  }
}

Once you receive the notification, you can get further details by making the following request:

curl --request GET 'https://api.belvo.com/receivables/transactions/?link={id}' \
-u [Secret Key ID]:[Secret Key PASSWORD]

Where:

{id} is the link_id you receive in your historical_update notification.

New receivable transactions available

You can receive a new_receivables_transactions_available notification whenever new receivable transactions are available for a banking recurrent link.

Once you receive the notification, you can query the receivable transactions resource to pull the details of these new transactions. For example, if you receive the following webhook:

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "RECEIVABLES_TRANSACTIONS",
  "webhook_code": "new_receivables_transactions_available",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "new_transactions": 19 // Number of new transactions found since last event
  }
}

You can request more information about receivable transactions with the following query to the Receivable Transactions endpoint using the created_at filter:

curl --request GET 'https://api.belvo.com/receivables/transactions/?link={id}&created_at__range={date1},{date2}' \
-u [Secret Key ID]:[Secret Key PASSWORD]

Where:

{id} is the link_id you received in the notification.
{date1} is the date when you previously received a notification, in YYYY-MM-DD format.
{date2} is the date you received the latest notification, in YYYY-MM-DD format.

Receivable transactions updated

Whenever Belvo identifies that a transaction has been updated in the institution (for example, a change to the description field or the value date), you will receive a receivables_transactions_updated webhook with a list of the transactions that have been updated.

{
   "webhook_id":"28364bef400f4374a80872b61ba204289",
   "webhook_type":"RECEIVABLES_TRANSACTIONS",
   "webhook_code":"receivables_transactions_updated",
   "link_id":"0284557b-df47-450a-po09e-7875195c2259",
   "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
   "external_id": "your_external_id",
   "data":{
      "count": 5, // Total number of transactions updated.
      "updated_transactions":[
         "7d0afe4c-373d-490c-90e4-06xx4cdd4a17", // The ID of the updated transaction.
         "a53759bc-ca02-46f0-b1d5-31xxcd54db41",
         "64ecc7df-f322-4934-82f5-3b3ae675ef4a",
         "0452ae0d-ax2f-4093-888c-bb2ae826xa0b",
         "9c266fff-ee3d-4389-adb3-1c5690d3c032"
      ]
   }

Once you receive the notification, you can pull the details on the updated transaction using the following call:

curl --request GET 'https://api.belvo.com/receivables/transactions/{id}/
-u [Secret Key ID]:[Secret Key PASSWORD]

Where:

{id} is one ID of a transaction you received in the webhook.