Powens Documentation
DocumentationChangelogConsoleWebsite
  • Documentation
  • Integration guides
    • Quick Start
      • API Overview
      • Add a first user and connection
    • ➖Bank
      • Introduction to Bank
      • Bank integration guide
    • ➖Check
    • ➖Wealth
    • ➖Pay
      • Getting started with Pay
      • Initiating a one-time payment with the Webview
      • Initiating a bulk payment with the Webview
      • Initiating a recurring payment with the Webview
      • Cancelling a payment
      • Validating your implementation with the test connector
      • Advanced
        • Listing connectors with Pay enabled programmatically
        • Implementing your own payment validation webview
        • Confirming payments manually
        • Changing the manual expiration time
        • Changing the maximum amounts for payments
    • ➖Trust
    • ➖Advisory (obsolete)
    • ➖Indicators
    • SCA & connection states
    • Webhooks
    • Advanced
      • Custom connection implementation
      • End-to-end encryption
      • Response signature
  • SDK
    • Connect SDK
    • Powens Connect iOS
  • Reference
    • API Reference
    • Console & Webview documentation
  • Ressources
    • Tools
      • Institutions & capabilities
      • Demo integration
      • Demo product
    • Glossary
  • Changelog
  • Legal notice
Powered by GitBook
On this page
  • Registering webhooks
  • Available webhook events
  • Technical integration
  • Authentication
  • Technical notes

Was this helpful?

  1. Integration guides

Webhooks

PreviousSCA & connection statesNextAdvanced

Last updated 3 months ago

Was this helpful?

Our API offers a way to obtain data of end-users using . After 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 in the 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 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.

Available webhook events

You can subscribe to the following events:

Event
Description

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

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.

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

OAuth2 authentication

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

See the 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.

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

We also support securing webhooks using , 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 :

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.

OAuth 2.0
client_credentials grant type of the protocol
full reference
USER_CREATED
USER_DELETED
USER_SYNCED
CONNECTION_SYNCED
CONNECTION_DELETED
ACCOUNTS_FETCHED
ACCOUNT_SYNCED
ACCOUNT_DISABLED
ACCOUNT_ENABLED
ACCOUNT_FOUND
ACCOUNT_OWNERSHIPS_FOUND
TRANSACTION_ATTACHMENTS_FOUND
SUBSCRIPTION_SYNCED
SUBSCRIPTION_FOUND
webhooks
a user connection has been configured
administration console
CONNECTION_SYNCED
register a webhook
obtained a permanent access token
configuration key
configuration
PAYMENT_STATE_UPDATED