Webhooks

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.

Registering webhooks

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 obtained a permanent access token for the user before you can receive webhook data.

Available webhook events

You can subscribe to the following events:

Event	Description
USER_CREATED	Emitted after a permanent user is created.
USER_DELETED	Emitted after a user is deleted.
USER_SYNCED	Deprecated. Emitted after multiple connections of a user have been synced.
CONNECTION_SYNCED	Emitted after a connection has been synced.
CONNECTION_DELETED	Emitted after a connection has been deleted.
ACCOUNTS_FETCHED	Emitted during a sync after bank accounts have been synchronized, but before the transactions are processed.
ACCOUNT_SYNCED	Emitted during a sync after a bank account was processed, including new transactions.
ACCOUNT_DISABLED	Emitted after a bank account was disabled.
ACCOUNT_ENABLED	Emitted after a bank account was enabled.
ACCOUNT_FOUND	Emitted after a new bank account was discovered.
ACCOUNT_OWNERSHIPS_FOUND	Emitted during a sync after a bank ownerships have been synchronized.
TRANSACTION_ATTACHMENTS_FOUND	Emitted during a sync after bank accounts have been synchronized, and after the transactions are processed.
SUBSCRIPTION_SYNCED	Emitted during a sync after a subscription was processed, including new documents.
SUBSCRIPTION_FOUND	Emitted after a new subscription was discovered.
PAYMENT_STATE_UPDATED	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).

Technical integration

Receiving the webhook data

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.

Expected response

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.

Compression of webhook payload

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.

To activate webhook data compression, use the webhooks.compression.enabled configuration key.

Authentication

We support three alternative mechanisms to secure webhooks sent to your servers:

Authentication with user-scoped token

The default mechanism for webhooks authentication is perfomed by adding the user token in every callback request in the authorization header:

authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

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).

Authentication with a HMAC signature header

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:

POST /webhooks/auth
authorization: Bearer <yourConfigurationToken>

{
  "type": "hmac_signature",
  "name": "My HMAC provider",
}

{
  "id": 2356,
  "type": "hmac_signature",
  "name": "My HMAC provider",
  "config": {
    "secret_key": <secret_key>
  }
}

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 Association 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.

OAuth2 authentication

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.

POST /webhooks/auth
authorization: Bearer <yourConfigurationToken>

{
  "type": "oauth",
  "name": "ACME provider",
  "config": {
    "url": "https://auth.example.org/token", // The full token endpoint URL of the provider
    "client_id": "123456", // Replace with your client ID
    "client_secret": "aJnr28jmdnIDNY9x11auihIX", // Replace with your client secret
    "grant_type": "client_credentials",
    "public_cert": "<yourPublicCert>", // Optional public certificate to use with the provider
    "private_cert": "<yourPrivateCert>" // Optional private certificate to use with the provider
  }
}

{
  "id": 2356,
  "type": "oauth",
  "name": "ACME provider"
}

Association

When a provider has been created, you can associate it with a webhook in the administration console.

Technical notes

Webhook vs. webhook data

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 data flusher

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.

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 configuration reference to update configuration values.

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.