A Webhook is a tool that allows you to receive a notification for a certain event. It allows you to set up an HTTPS URL in our platform for certain events and you will receive a JSON POST event in that URL, with specific event data.

To subscribe to Webhook events, you can either:

If you create a Webhook instance directly, you'll be subscribing to all the cases of events of the specified event type. Instead, if you do it by specifying the webhookUrl when creating an Item, or creating a Connect Token, you'll be notified about all the events, but only related to that specific resource. Which is, either to that Item specifically, or to the related item(s) created using that Connect Token.

Currently, we support registering for the following events:

EventDescription
item/createdAn item was created and finished connecting succesfully.
item/updatedAn item was updated and synced successfully.
item/deletedAn item was deleted successfully.
item/errorAn item has encountered errors in its execution.
item/waiting_user_inputAn item is blocked waiting for user input to continue.
item/login_succeededAn item has successfully logged in to the provider and it's collecting the data.
connector/status_updatedA connector has changed status (ONLINE/UNSTABLE/OFFLINE).
This event informs the affected connector ID and updated status. Check the Connectors endpoint to see all connectors and their IDs.
allReceive all events.

To register for a specific event you will have to send the desired one as the event to attach. Alternatively, you can just use the option all to receive all events associated.

We only accept HTTPS URLs. Localhost URL are not allowed to be used, you will have to provide an HTTPS URL using ngrok or other tools to provide public secured URLs.

📘

Tip

To test this functionality, you can use RequestCatcher, which is a tool that will just receive our notification and show you the payload.

You can easily create a catcher with just a name in seconds.

Payload parameters

When doing the POST request, all webhooks will send the following parameters in JSON format:

  • id: primary identifier of the resource that was notified.
  • event: Event's name (item/created, item/updated, item/error, etc.)
  • triggeredBy: For all events except item/deleted and connector/status_updated, who triggered the event (USER/CLIENT/SYNC)

Example:

{
  "event":"item/created",
  "id":"a5c763cb-0952-457b-9936-630f79c5b016",
  "itemId":"a5c763cb-0952-457b-9936-630f79c5b016",
  "triggeredBy": "USER"
}
{
  "event":"item/updated",
  "id":"a5c763cb-0952-457b-9936-630f79c5b016",
  "itemId":"a5c763cb-0952-457b-9936-630f79c5b016",
  "triggeredBy": "USER"
}
{
  "event":"item/deleted",
  "id":"a5c763cb-0952-457b-9936-630f79c5b016",
  "itemId":"a5c763cb-0952-457b-9936-630f79c5b016"
}
{
  "event": "item/error",
  "id": "d161a74a-8bc8-4093-88de-724312969b0d",
  "itemId": "d161a74a-8bc8-4093-88de-724312969b0d",
  "error": {
    "code": "USER_INPUT_TIMEOUT",
    "message": "User requested input had expired",
    "parameter": "token"
  },
  "triggeredBy": "USER"
}
{
  "event": "item/waiting_user_input",
  "id": "d038aaa6-35f2-4f06-8b8a-c464a4a61fc2",
  "itemId": "d038aaa6-35f2-4f06-8b8a-c464a4a61fc2",
  "triggeredBy": "USER"
}
{
  "event":"item/login_succeded",
  "id":"a5c763cb-0952-457b-9936-630f79c5b016",
  "itemId":"a5c763cb-0952-457b-9936-630f79c5b016",
  "triggeredBy": "USER"
}
{
  "event":"connector/status_updated",
  "id":"201",
  "data": {
    "status":"UNSTABLE"
  }
}

Handling notifications

When we send you a webhook notification, two things can happen:

  • Your API responds 2XX in less than 5 seconds (success)
  • Your API responds a different status, it does not respond in 5 seconds (failure)

When there is a failure, we retry the notification up to 10 times over the next three days. After that, the notification will be lost.

We strongly recommend that your API returns 2XX right after receiving a notification and then does its own processing after that. This way, if your processing takes more than 5 seconds, we will not interpret it as a failure, therefore avoiding unwanted retries of the same notification.

Webhook headers

When creating a webhook, you can specify a headers object to send specific headers in your webhook notifications. This can be useful, for instance, if your webhook URL is secured with an API Key. You can add headers to your webhook like this:

{
  "url": "example.com",
  "event": "all",
  "headers": {
    "Authorization": "My API key",
    "X-CLIENT-ID": "Some extra information"
  }
}

📘

For more information see Webhook in our API reference.