Webhooks
Last updated
Last updated
Our API offers a way to obtain data of end-users using webhooks. After a user connection has been configured using our API endpoints, these callbacks are the most efficient way to get up-to-date user data.
We highly recommend using webhooks instead of implementing an API-polling mechanism.
You can register a webhook in the administration console of your domain. As many webhooks as needed can be registered.
The console also lets you test webhooks triggering and handling. For instance, after you have configured a webhook for the CONNECTION_SYNCED event, you can test that the callback is properly triggered when a user creates a new connection to his bank accounts in the webview.
Webhooks are only triggered for permanent users: you must have for the user before you can receive webhook data.
You can subscribe to the following events:
Emitted after a permanent user is created.
Emitted after a user is deleted.
Deprecated. Emitted after multiple connections of a user have been synced.
Emitted after a connection has been synced.
Emitted after a connection has been deleted.
Emitted during a sync after bank accounts have been synchronized, but before the transactions are processed.
ACCOUNTS_CATEGORIZED
Emitted during a sync after bank accounts have been synchronized, and after the transactions are processed.
Emitted during a sync after a bank account was processed, including new transactions.
Emitted after a bank account was disabled.
Emitted after a bank account was enabled.
Emitted after a new bank account was discovered.
Emitted during a sync after a bank ownerships have been synchronized.
Emitted during a sync after bank accounts have been synchronized, and after the transactions are processed.
Emitted during a sync after a subscription was processed, including new documents.
Emitted after a new subscription was discovered.
Emitted after a payment has been updated.
If the user is still in a temporary state when the webhook events should be triggered (USER_CREATED for instance), the callback will be sent as soon as you make the user permanent.
Webhooks are triggered:
after you ask for a specific action through the API and
after a background synchronization (every 24h by default).
By default, webhooks are performed using HTTP POST requests, with JSON body data.
The autosync.cfonb config key is available to change the format of the ACCOUNT_FOUND, CONNECTION_SYNCED and USER_SYNCED callbacks to the CFONB format.
See the full reference above for the detailed format of each webhook. Alongside the event specific data in the request body, an additional id_webhook_data integer field is also included. It allows you to identify the webhook payload uniquely.
Your server must respond with a 2XX (success) HTTP response code when a webhook is received on the provided URL, otherwise we consider that the webhook data has not been received.
If a webhook push failed, we will retry pushing that data until it is properly accepted.
During the first synchronization of a connection, your webhook will receive all the user's transactions and/or documents, which may produce a very large HTTP payload of multiple MBs. You can enable webhook compression to reduce the size of the exchanged content in the following cases:
Your web server is configured to limit the HTTP body to a size that is not sufficient.
You have more CPU resources than bandwidth.
When compression is activated, the HTTP body sent to your webhook will be compressed in gzip format and the HTTP header content-encoding will be set to gzip.
We support three alternative mechanisms to secure webhooks sent to your servers:
The default mechanism for webhooks authentication is perfomed by adding the user token in every callback request in the authorization header:
When receiving a webhook, you can check that the provided token matches the record you have for the user, and reject the call otherwise.
This is only available for webhooks related to a specific user (e.g. not PAYMENT_STATE_UPDATE).
An additional authentication method is available, which uses a hash-based message authentication code (HMAC). The code is generated with a shared secret, and authentication is performed by the client by recalculating the HMAC signature. This asserts that the sender of the webhook data knows the secret.
In order to enable it, you need to create a new auth_provider of type hmac_signature:
The secret used to compute the HMAC signature can be found in the config object.
You should preserve this secret key safely as you will not be able to access it anymore after this.
See the "Association" section below for linking this newly created provider to your webhook(s).
The provider will add two headers to each webhook data:
BI-Signature-Date containing a datetime in UTC ISO 8601 format generated during the request creation.
BI-Signature = BASE_64(HMAC_SHA256(<METHOD> + "." + <endpoint> + "." + <date> + "." + <payload>, secret_key)) where:
is the HTTP method used (POST), in capital letters;
is the listening URL endpoint of the client;
is the value contained in the BI-Signature-Date header;
is the webhook data payload.
Example calculation of a signature:
BASE_64(HMAC_SHA256('POST./v1/webhook-listener.2022-06-27T11:08:52.577831Z.{"id": 1, "state": "done", ...}', secret_key))
You can then reject any webhook data where the signature does not match your computation.
We also support securing webhooks using OAuth 2.0, the industry-standard protocol for authorization. When an OAuth 2.0 provider configuration is defined and associated with your wehbooks, callbacks will be secured with access tokens obtained from the authorization server and added to the authorization header.
The provided authorization server endpoint must fully support the client_credentials grant type of the protocol:
accept a standard payload with client_id, client_secret and grant_type (set to client_credentials);
respond with a JSON entity with access_token, token_type (must be bearer), and optionnally expires_in and refresh_token to implement tokens expiration;
optionally, support a additional layer of security using a pair of certificates.
Registration
Configuration of auth providers will soon be available in the administration console. In the meantime, you can register them using the API.
You can use an API endpoint available on your domain to register a new provider. The call must be authenticated using your configuration token, available in the administration console. All parameters are mandatory, except from public_cert and private_cert.
Association
When a provider has been created, you can associate it with a webhook in the administration console.
It is important to distinguish a webhook from its data.
A webhook is a "registration" to a webhook event (USER_CREATED, CONNECTION_SYNCED, ...) including an URL that will receive the webhook data at event time.
A webhook request payload includes data associated with the webhook's event. For example, a webhook registered with the USER_CREATED event will include data with user information.
Webhook requests are emitted immediately at creation (when the related event occurs). In case of failure, our webhook system uses a "flusher" retrying to send webhook data regularly. The flusher stops after 10 consecutive failures (or 2 timeouts) per webhook. In such case, it will attempt to send unprocessed webhook data at next execution.
You can monitor your webhook's health (average sending duration and sending success rate) through its health_data property. A warning is also displayed in a warning property if at least one of these values reaches a critical threshold.
To activate webhook data compression, use the webhooks.compression.enabled .
An email can be sent when the flusher is failing. You must set the biapi.manager.email config key to receive it. In order to prevent email flooding, the config key webhooks.alerts_frequency determines the minimum number of days between two emails per webhook (default: 1 = one day, can be 0.5 for twice a day). When the problem is solved, a flush recovery email is sent. See reference to update configuration values.