Skip to main content

Using Queues and events

Queues & events#

Events are generated in order to be able to follow the evolution of the various asynchronous processes. These events will contain several pieces of information like status which allow the client to be aware of various actions to be taken.

Events are dated, named and linked to a resource. You can understand everything that happened: credentials validation, connection to the provider, account recovery... Events are categorized into different types like global, login, choose bank, synchronization, consent, ...

The queue contains the list of events that occur during asynchronous processes (add a connection, synchronization of datas). You can retrieve a queue identifier when you subscribe to a new queue or use the widget with the add a connection, edit credentials or user input endpoints.

To be able to receive these events, the process is rather simple and you just have to:

  • Subscribe to a queue, dedicated to the user, before starting synchronization.
  • Poll the queue to track progress and retrieve new events. Events will stack in the queue asynchronously.

In the Oxlin environment, a bank connection has 2 types of none exclusive channels:

  • EMBEDDED: corresponding to the 'scraping' type connection
  • REDIRECT: corresponding to the 'DSP2 API' type connection

The events are linked to a channel using the channel_definition_id and may be emitted for the channels available. The integrator needs to consume events from both channels to ensure all data is available. For example a LIST_ACCOUNTS job for an existing connection with two channels will provide a first account list for the REDIRECT channel and a second for the EMBEDDED one.

The description of the events are provided in the reference documentation.

For example, the following channel events are usefull to follow the actions needed to be taken:

  • AUTH_FAILED: Authentication failed during last channel synchronization.
  • TOKEN_EXPIRED: The PSD2 API token expired. The user must re-authenticate to restore the channel synchronization.
  • PASSWORD_CHANGE_REQUIRED: The provider requires the user to change his password.
  • USER_ACTION_REQUIRED: The provider requires the user to fulfil an action (accepting new terms and conditions, filling a form, etc).
  • CHALLENGE_REQUIRED: The provider required a challenge (by SMS, mail, etc.).

Subscribe to a new queue#

Since the queue will receive events, it is essential that it has been created before starting synchronization. The queue expires 15 minutes after the last query. The timer for a queue is reset as long as you keep listening to it.

To subscribe to a queue, simply use our endpoint POST /queues/subscribe with a valid access token.

You will retrieve an identifier that will allow you to listen to events stacked in the queue.

Example:

# subscribe to a queue with
curl -X POST \
https://sandbox-api.oxlin.io/v2.1/queues/subscribe \
-H 'authorization: Bearer {access_token}' \
-d '{
"topics": ["connections"]
}'
# it returns the queue id in the header location
HTTP/1.1 201 Created
location: /queues/{queue_id}

Poll the queue#

Events will stack in the Queue asynchronously. To track progress and retrieve new events, you need to poll the queue. The endpoint for this action is GET /queues/{queue_id}

Example:

# Poll the queue
curl https://sandbox-api.oxlin.io/v2.1/queues/{queue_id} \
-H 'authorization: Bearer {access_token}'
# While the queue is empty, you will receive a 204 HTTP status code
HTTP/1.1 204 No Content
# If queue contains events
HTTP/1.1 200 OK
# Here is one event from the list.
[
...
{
"id":"14",
"event_type":"SYNC_ALL_STARTED",
"resource_type":"CONNECTION",
"creation_date":1527761001,
"channel_definition_id": "redirect1",
"resource":{
"id":"{connection_id}",
"provider_id":"200",
"name":"WBX Test Bank",
"status":"SUCCESS",
"creation_date":0,
"channels":[{
"channel_definition_id": "8701",
"expires": 1527761000,
"status": "RUNNING",
"last_success_date":1527760963,
"last_end_date":1527760963
},{
"channel_definition_id": "8700",
"status": "RUNNING",
"last_success_date":1527760963,
"last_end_date":1527760963
}]
}
},
...
]
# The Synchronization ends when there is an event_status=SYNC_ALL_SUCCESS