# Webhooks Our API offers a way to obtain data of end-users using [webhooks](https://en.wikipedia.org/wiki/Webhook). After [a user connection has been configured](https://docs.powens.com/documentation/integration-guides/quick-start/add-a-first-user-and-connection) using our API endpoints, these callbacks are the most efficient way to get up-to-date user data. {% hint style="warning" %} We highly recommend using webhooks instead of implementing an API-polling mechanism. {% endhint %} ### Registering webhooks You can [register a webhook](https://docs.powens.com/documentation/quick-start#register-a-webhook) in the [administration console](https://console.budget-insight.com/) 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`](https://docs.budget-insight.com/reference/connections#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. {% hint style="info" %} Webhooks are only triggered for *permanent* users: you must have [obtained a permanent access token](https://app.gitbook.com/s/jaOZc6CNFstFU2WHDyoU/overview/authentication) for the user before you can receive webhook data. {% endhint %} ### Available webhook events You can subscribe to the following events:
EventDescription
USER_CREATEDEmitted after a permanent user is created.
USER_DELETEDEmitted after a user is deleted.
USER_SYNCEDDeprecated. Emitted after multiple connections of a user have been synced.
CONNECTION_SYNCEDEmitted after a connection has been synced.
CONNECTION_DELETEDEmitted after a connection has been deleted.
ACCOUNTS_FETCHEDEmitted during a sync after bank accounts have been synchronized, but before the transactions are processed.
ACCOUNT_CATEGORIZEDEmitted during a sync after bank accounts have been synchronized, and after the transactions are processed.
ACCOUNT_SYNCEDEmitted during a sync after a bank account was processed, including new transactions.
ACCOUNT_DISABLEDEmitted after a bank account was disabled.
ACCOUNT_ENABLEDEmitted after a bank account was enabled.
ACCOUNT_FOUNDEmitted after a new bank account was discovered.
ACCOUNT_OWNERSHIPS_FOUNDEmitted during a sync after a bank ownerships have been synchronized.
TRANSACTION_ATTACHMENTS_FOUNDEmitted during a sync after bank accounts have been synchronized, and after the transactions are processed.
SUBSCRIPTION_SYNCEDEmitted during a sync after a subscription was processed, including new documents.
SUBSCRIPTION_FOUNDEmitted after a new subscription was discovered.
PAYMENT_STATE_UPDATEDEmitted 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](#available-webhook-events) 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](https://app.gitbook.com/s/jaOZc6CNFstFU2WHDyoU/api-setup/configuration#get-configuration). ### 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. {% hint style="warning" %} This is only available for webhooks related to a specific user (e.g. not `PAYMENT_STATE_UPDATE`). {% endhint %} #### 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`: ```json POST /webhooks/auth authorization: Bearer { "type": "hmac_signature", "name": "My HMAC provider", } ``` ```json { "id": 2356, "type": "hmac_signature", "name": "My HMAC provider", "config": { "secret_key": } } ``` The secret used to compute the HMAC signature can be found in the `config` object. {% hint style="warning" %} You should preserve this secret key safely as you will not be able to access it anymore after this. {% endhint %} 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( + "." + + "." + + "." + , 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](https://oauth.net/2/), 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](https://oauth.net/2/grant-types/client-credentials/): * 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`. ```json POST /webhooks/auth authorization: Bearer { "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": "", // Optional public certificate to use with the provider "private_cert": "" // Optional private certificate to use with the provider } } ``` ```json { "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](https://app.gitbook.com/s/jaOZc6CNFstFU2WHDyoU/api-setup/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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.powens.com/documentation/integration-guides/webhooks.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.