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.

Available webhook events

You can subscribe to the following events:

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.

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.

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.

Last updated