Presentation

Definition

Webhooks are a way to trigger an action following an event. They are mainly used to make two systems communicate with each other. Webhooks are a simple, effective manner of communicating to a system a state change that occurred in another system.

Webhooks will notify distributors of state changes of various objects on our side, avoiding frequent calls to our API (polling).

Setup

A distributor can choose to create webhooks in our app.

For now, we are supporting the following state changes:

• creation of a new product (Product)

• update of an import task (ImportTask)

• update of a send task (SendTask)

• update of a platform state (DspState)

When creating a webhook, the distributor will need to fill in the following information:

• the type of state change they wish to be notified about,

• an unauthenticated URL that will be called when the state of the object is changed.

We will perform a POST request on this URL providing the following attributes in JSON :

• <id> = the id of the updated object

• <value> = the new value of the property

• <time> = the date when the object underwent a state change

• <product_id> = the product id related if relevant

Example:

URL: https://api.idol.io/api/v1/callbacks

We will then trigger an HTTP call on the URL:

POST https://yourdomain.com/callbacks
{
    "id": "1",
    "value": "1",
    "time": "2022-09-12 00:00:00",
    "product_id": "1"
}

Webhooks