Owners (Webhooks)

Reference information for our Owners webhook events.

Historical update

As soon as your banking link is created, we asynchronously load the owner information available for the link and will send you the following webhook:

Webhook CodeDescription
historical_updateThe total number of owners found for the link.

In the webhook payload we include the number of owners found for the link.

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "OWNERS",
  "process_type": "historical_update",
  "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_owners": 2 // Total number of owners
  }
}

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

curl --request GET 'https://api.belvo.com/api/owners/?link=link_id' \
-u [Secret Key ID]:[Secret Key PASSWORD]
Query ParameterDescriptionExample
linkThe link_id you received in the webhook notification.2f5d361d-dad6-45d4-a0bf-26d479766067

New owners available

According to your chosen refresh rate, Belvo will asynchronously retrieve data about any new accounts that have appeared for the given link since the last update.

Webhook CodeDescription
new_owners_availableThe number of new owners found since the last update.

In the webhook payload we include the number of new owners found for the link.

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "OWNERS",
  "process_type": "recurrent_update",
  "webhook_code": "new_owners_available",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28",
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "new_owners": 1 // Number of new owners
  }
}

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

curl --request GET 'https://api.belvo.com/api/owners/?link=link_id' \
-u [Secret Key ID]:[Secret Key PASSWORD]
Query ParameterDescriptionExample
linkThe link_id you received in the webhook notification.2f5d361d-dad6-45d4-a0bf-26d479766067