Guides
API StatusAPI ReferenceError DocsInstitutionsSupportSign inCreate a Sandbox account

Consents (Webhooks)

Reference information for our Consent webhook events.

Suggest Edits

🚧

Only available for recurrent links

You will only receive CONSENT webhook events for recurrent links.

Consent about to expire

📘

Opt-in to receive consent about to expire webhooks

If you would like to receive webhooks for consents that are about to expire, please reach out to our support team.

You can receive an openfinance_consent_about_to_expire event when the consent for one of your OFDA links will expire within seven days of the recurrent link's refresh.

For example, if you have a monthly refresh rate for a link that renews on the second day of each month, and the link's consent expiry date is the sixth of that month, you will receive an openfinance_consent_about_to_expire event. However, if you have another link that renews on the second day of each month but the consent expiry date is the tenth of that month, you will not receive an event.

📘

Prompt your user to renew consent

Once you receive this event, you can prompt your user to renew their consent using the My Belvo Portal.

{
  "webhook_id": "37a084ee0741437fa7a95393b5636f7b",
  "webhook_type": "CONSENT",
  "process_type": "recurrent_update",
  "webhook_code": "openfinance_consent_about_to_expire",
  "link_id": "da9822bb-5bd6-4a0a-b64d-0aefcc9e86b0",
  "external_id": null,
  "data": {
    "consent_id": "9e763d19-15a4-410c-a106-18c0f60ca5eb", // The consent ID.
    "consent_due_date": "2024-12-26T10:45:58.000Z", // ISO-8601 timestamp of when the consent will expire.
    "action": "renew", // An indication of what action you need to take. For openfinance_consent_about_to_expire webhooks, this is always set to renew.
    "institution": "ofmockbank_br_retail", // The institution that the user provided their consent for.
    "institution_display_name": "OF Mockbank", // The display name of the institution.
    "institution_icon_logo": "https://logo.com" // The URL to the institution's logo.
  }
}

Consent expired

You can receive a consent_expired event when the consent for one of your OFDA links has expired.

📘

Prompt your user to renew consent

Once you receive this event, you can prompt your user to renew their consent using the My Belvo Portal.

{
  "webhook_id": "e6f08793f967445fb74ce16beae665bc",
  "webhook_type": "CONSENT",
  "process_type": "recurrent_update",
  "webhook_code": "openfinance_consent_expired",
  "link_id": "3d3364b7-0175-483d-a58b-b471f251e533", // The link ID associated with the consent.
  "external_id": null,
  "data": {
    "consent_id": "29a54e55-21f0-4d02-8e34-797ab7d43940", // The consent ID.
    "action": "renew", // An indication of what action you need to take. For openfinance_consent_expired webhooks, this is always set to renew.
    "institution": "ofmockbank_br_retail", // The institution that the user provided their consent for.
    "institution_display_name": "OF Mockbank", // The display name of the institution.
    "institution_icon_logo": "https://logo.com" // The URL to the institution's logo.
  }
}

Once you receive the notification, you can prompt your user to renew their consent using the My Belvo Portal.

Consent revoked

You can receive an openfinance_consent_with_unrecoverable_resources event when a consent has been revoked due to the pre-existing resources being unavailable. An example of when you may receive this event is when a user has granted their consent to access several accounts and at a later date closed those accounts.

{
  "webhook_id": "e6f08793f967445fb74ce16beae665bc",
  "webhook_type": "CONSENT",
  "process_type": "recurrent_update",
  "webhook_code": "openfinance_consent_with_unrecoverable_resources",
  "link_id": "da9822bb-5bd6-4a0a-b64d-0aefcc9e86b0",
  "external_id": null,
  "data": {
    "consent_id": "29a54e55-21f0-4d02-8e34-797ab7d43940", // The consent ID.
    "institution": "ofmockbank_br_retail", // The institution that the user provided their consent for.
    "message": "The consent was revoked because it was unrecoverable" // Error message regarding the revoked consent.
  }
}

Consent temporarily unavailable

You can receive an openfinance_consent_with_temporarily_unavailable_resources event when a consent is temporarily unavailable due to the pre-existing resources being unavailable. An example of when this may occur is when the user granted their consent to access a given account, but has not used that account for a while (the number of days until an account is marked as inactive depends on each institution).

{
  "webhook_id": "745156bbbd0d47b0a33ff995d7b4e5d8",
  "webhook_type": "CONSENT",
  "process_type": "recurrent_update",
  "webhook_code": "openfinance_consent_with_temporarily_unavailable_resources",
  "link_id": "da9822bb-5bd6-4a0a-b64d-0aefcc9e86b0",
  "external_id": null,
  "data": {
    "consent_id": "29a54e55-21f0-4d02-8e34-797ab7d43940", // The consent ID.
    "institution": "ofmockbank_br_retail", // The institution that the user provided their consent for.
    "message": "The consent is temporarily unusable" // Error message regarding the temporarilt unavailable consent.
  }
}

Updated 6 months ago