Skip to main content

Using webhooks

Webhooks#

Our service provides a webhook mechanism, allowing an integrator to be notified of some business events. These events will be sent on a URL communicated by the integrator. This URL must be an https URL (mutual TLS can optionally be set up). The events will be sent with POST requests.

The events are serialized in json. The different fields are:

fielddescription
idThe unique id of the event.
event_typeThe type of event, among: UDPATED, CREATED, DELETED.

The event type specifies what happened on the resource the event is related to.

The only event type implemented for now is UPDATED.
resource_typeThe type of the resource this event is related to.

The only value for now is CONNECTIONS.
creation_dateCreation time of the event (timestamp in seconds).
channel_definition_idSee below (A).
resourceA representation of the resource this event is related to. See below (B).
new_transactionsA boolean field specifying whether the synchronization brought new transactions. This field is specific to CONNECTIONS UPDATED events.

(A) The channel_definition_id field allows to handle PSD2 APIs and REDIRECT authentication.

A connection may have:

  • a REDIRECT channel, allowing getting payment accounts through PSD2 APIs
  • and/or an EMBEDDED channel, allowing getting other accounts through scraping (savings accounts, loans, etc).

A webhook event will be fired everytime a channel synchronization finishes. So, we will possibly have 2 events for a single synchronization of a connection. The channel_definition_id field is here to specify which channel the event is related to.

(B) For connection resources, the resource field

fielddescription
idThe id od the resource as returned or handled in any other endpoint of the API.
user_idThe id of the user the connection belongs to.
statusThe status of the connection resource (not the status of the channel the event is related to).

Here is a full example of event:

{
"id": "abc123456",
"event_type" : "UPDATED",
"resource_type" : "CONNECTIONS",
"creation_date": 1509955448,
"channel_definition_id" : "8701",
"resource" : {
"id": "14775",
"user_id": "123456",
"status": "SUCCESS"
},
"new_transactions" : true
}

The status list is defined in the reference doc.

Using webhooks to get new transactions#

Webhooks can be used to get new transactions on the fly: every time a "connection updated" event is received by the integrator, it can call the 'GET /transactions' endpoint. The integrator can use the new_transactions flag to know whether there are new transactions to get.

This has to be done on a per account basis. For each account, the integrator must use the import date of the last transaction the integrator previously got for this account.

Since there is one "connection updated" event per channel, for each event, the integrator can get the new transactions for the accounts currently attached to the channel of the event. The link between an account and a channel is specified by the last_channel_definition_id field in the accounts (see 'GET /accounts endpoint').

Example:

`GET /transactions?account_id=abc123&start_import_date=1574767574`

Limitation#

Our current webhook implementation does not provide any retry mechanism. If a "connection updated" event is not received properly by the integrator, it is currently lost. It is thus important not to rely on the webhooks only to get new transactions.