Consents

Reference information for our Consent webhook events.

Consent about to expire

You can receive an openfinance_consent_about_to_expire event when the consent for one of your OFDA links will expire soon.

📘

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",
  "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",
  "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",
  "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",
  "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.
  }
}