Tax declarations (Webhooks)

Reference information for our Tax declaration webhook events.

Historical update

As soon as your fiscal link for Colombia is created, we asynchronously load the last year of tax declaration information for the link. You will receive a historical_update notification whenever the tax declaration history is available for you to access.

{
  "webhook_id": "80fa38b7cad34950b210626abd86bfe9",
  "webhook_type": "TAX_DECLARATIONS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_tax_returns": 2, // Total number of tax declarations found
    "first_tax_declaration_date": 2021, // Date of the first tax declaration found
    "last_tax_declaration_date": 2022 // Date of the last tax declaration found
  }
}
{
  "webhook_id": "80fa38b7cad34950b210626abd866549",
  "webhook_type": "TAX_RETURNS",
  "process_type": "historical_update",
  "webhook_code": "historical_update",
  "link_id": "2f5d361d-dad6-45d4-a0bf-26d479766067",
  "data": {
    "type": "monthly", // either yearly or monthly
    "total_tax_returns": 7, // Total number of tax returns found
    "first_tax_return_year": 2017, // First filed tax return
    "last_tax_return_year": 2018 // Last filed tax return
  }
}

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

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

Where:

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