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.

Currently, we support registering for the following events:




An item was created and it is connecting to provider.


An item was updated and synced successfully.


An item was deleted successfully.


An item has encountered errors in its execution.


An item it's blocked waiting for user input to continue.


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


Receive all events.

To register for a specific event you will have to send the desired one as the event to attach. There is also an 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.

Just to review the 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.)


  "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"
  "event": "item/waiting_user_input",
  "id": "d038aaa6-35f2-4f06-8b8a-c464a4a61fc2",
  "itemId": "d038aaa6-35f2-4f06-8b8a-c464a4a61fc2"
  "data": {

Retry policies

A webhook notification expects a 2XX status code in the response if you need to do some work with the event you should process after replying back.

If there is a communication error (no response or an error) we will retry the notification 10 times over the next three days in incremental intervals of time. After that, the notification will be lost.

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.