Webhooks
Our service provides a webhook mechanism, allowing an integrator to be notified as soon as a connection has been updated. These events will be sent on a URL communicated by the integrator. Note that the setup is performed by the Linxo Support Team, on demand. This URL must be an https URL (mutual TLS can optionally be set up).
So when a connection has been updated (for instance, new transactions have been synchronized with the bank), an event will be sent over the webhook URL using the POST method.
The webhook is very useful as it allows integrators to rationalize their API calls. They can interrogate the endpoint as soon as they have been notified of an event, instead of scheduling automatic pooling at fixed intervals.
The fields related to the events
The events are serialized in JSON. The fields available is the events are as follows :
| field | description |
|---|---|
id | The unique id of the event. |
event_type | The 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_type | he type of the resource this event is related to.The only value for now is CONNECTIONS. |
creation_date | Creation time of the event (timestamp in seconds). |
channel_definition_id | Please refer to the dedicated chapter below. |
resource | A representation of the resource this event is related to. Please refer to the dedicated chapter below. |
new_transactions | A boolean field specifying whether the synchronization brought new transactions. This field is specific to CONNECTIONS UPDATED events. |
‘channel_definition_id’
The channel_definition_id field was added as part of the changes of our API v2.1, designed to handle PSD2 APIs and REDIRECT authentication. In API v2.1, a connection may have:
A connection may have:
- a
REDIRECTchannel, allowing getting payment accounts through PSD2 APIs - and/or an
EMBEDDEDchannel, 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 : one for the REDIRECT channel, and the other for the EMBEDDED channel.
The channel_definition_id field is here to specify which channel the event is related to.
‘resource’
For connection resources (which is the only resource type implemented for now), the resource contains only 3 fields, which are :
| field | description |
|---|---|
id | The id of the resource as returned or handled in any other endpoint of the API. |
user_id | The id of the user the connection belongs to. |
status | The status of the connection resource (not to be confused with the status of the channel the event is related to). |
Note that the resource is similar to the one returned by the GET /connections endpoints, except it contains 2 additional fields, which are :
| field | description |
|---|---|
account_count | An integer field specifying the number of accounts included in the connection.This is the number of accounts returned by 'GET /accounts?connectionid={connection_id}'. |
accounts | An array field, containing the accounts included in the connection, as they are returned by API endpoints 'GET /accounts' or 'GET /accounts/{connection_id}'. |
Example of an event showing new transactions
The connection_updated field contains only one field, named new_transactions. This field is a boolean field specifying whether the synchronization brought new transactions.
Here is a full example of event, for a connection with 2 accounts:
{
"id": "abc123456",
"event_type" : "UPDATED",
"resource_type" : "CONNECTIONS",
"creation_date": 1509955448,
"channel_definition_id" : "24601",
"resource" : {
"id" : "123",
"user_id" : "321",
"provider_id" : "246",
"name" : "Caisse d'Epargne",
"status" : "SUCCESS",
"creation_date" : 1286641695,
"auto_sync" : true,
"logo_url" : "https://static.oxlin.io/common/pictures/providers_logos/246.png",
"channels" : [
{
"channel_definition_id" : "24600",
"mode" : "EMBEDDED",
"status" : "SUCCESS",
"last_success_date" : 1607106094,
"last_end_date" : 1607106094,
"credentials" : [
{
"id" : "2460000",
"masked_value" : "*****1234"
}
],
"account_types" : [ "CHECKINGS", "SAVINGS", "LOAN", "CREDIT_CARD" ],
"channel_definition_unavailable" : false
},
{
"channel_definition_id" : "24601",
"mode" : "REDIRECT",
"expires" : 1609943012,
"status" : "SUCCESS",
"last_success_date" : 1607106070,
"last_end_date" : 1607106070,
"credentials" : [ ],
"account_types" : [ "CHECKINGS", "CREDIT_CARD" ],
"channel_definition_unavailable" : false
}
],
"owner" : {
"name" : "M JEAN DUPONT"
},
"consent_per_account" : false,
"account_count" : 2,
"accounts" : [
{
"id": "222",
"connection_id": "123",
"name": "Compte Courant",
"currency": "EUR",
"balance": 1234.56,
"balance_date": 1607353181,
"iban": "FR7612345678901234567890123",
"status": "ACTIVE",
"type": "CHECKINGS",
"creation_date": 1286641717,
"account_number": "12345678901",
"owner": {
"name": "Mr Jean Dupont"
},
"usage": "PERSONAL",
"last_channel_definition_id": "24601"
},
{
"id": "111",
"connection_id": "123",
"name": "Livret A",
"currency": "EUR",
"balance": 10000,
"balance_date": 1607310062,
"iban": "FR7609876543210987654321098",
"status": "SUCCESS",
"type": "SAVINGS",
"creation_date": 1286641717,
"account_number": "09876543210",
"owner": {
"name": "Mr Jean Dupont"
},
"usage": "PERSONAL",
"savings": {
"type": "LIVA",
"savings_type": "LIQUID",
"yield_rate": 0.5
},
"last_channel_definition_id": "24600"
}
]
},
"connection_updated" : {
"new_transactions" : true
}
}
Case of a connection that has more than 100 accounts
When a connection has more than 100 accounts:
- the
accountsarray field will be empty - the
account_countfield will contain the number of accounts included in the connection
It is up to the integrator to handle this specific case (it is possible to perform several calls to the API, depending on pagination parameters). We strongly recommend not to hard code the 100 limit, which could change in the future. Having an account_count greater than 0 with an empty list of accounts is the right way to detect this case.
Example of event, for a connection with 102 accounts:
{
"id": "abc123456",
"event_type" : "UPDATED",
"resource_type" : "CONNECTIONS",
"creation_date": 1509955448,
"channel_definition_id" : "24601",
"resource" : {
"id" : "123",
"user_id" : "321",
"provider_id" : "246",
"name" : "Caisse d'Epargne",
"status" : "SUCCESS",
"creation_date" : 1286641695,
"auto_sync" : true,
"logo_url" : "https://static.oxlin.io/common/pictures/providers_logos/246.png",
"channels" : [
{
"channel_definition_id" : "24600",
"mode" : "EMBEDDED",
"status" : "SUCCESS",
"last_success_date" : 1607106094,
"last_end_date" : 1607106094,
"credentials" : [
{
"id" : "2460000",
"masked_value" : "*****1234"
}
],
"account_types" : [ "CHECKINGS", "SAVINGS", "LOAN", "CREDIT_CARD" ],
"channel_definition_unavailable" : false
},
{
"channel_definition_id" : "24601",
"mode" : "REDIRECT",
"expires" : 1609943012,
"status" : "SUCCESS",
"last_success_date" : 1607106070,
"last_end_date" : 1607106070,
"credentials" : [ ],
"account_types" : [ "CHECKINGS", "CREDIT_CARD" ],
"channel_definition_unavailable" : false
}
],
"owner" : {
"name" : "M JEAN DUPONT"
},
"consent_per_account" : false,
"account_count" : 102,
"accounts" : [
]
},
"connection_updated" : {
"new_transactions" : true
}
}