Protocol

Protocol: over HTTP

ACTITO Webhooks module will push events as HTTP POST calls on a target endpoint url.

These urls should be publicly accessible over the internet.

The detailed data of the event will be pushed as the request body in JSON format. In order to accept this body, your endpoint should accept application/json content type.

Security

For more security, we force the use of HTTPS when defining the target url of your endpoint so that the data can not be sniffed.

More over, when defining your subscription, you can provide http headers that ACTITO will include in the calls to your endpoint. You should then use those headers to provided a shared secret header that only you and ACTITO know. In that way, you'll be able to check that the pushed payload you receive on your endpoint has been made by ACTITO.

To define that secret header and any other header you would like ACTITO to include, check the following sample:

{  "on": "PROFILE_TABLE",  "eventType": "CREATE",  "onElementId": "123456",  "onFields": [    "emailAddress"  ],  "targetUrl": "https://myactitowebhookendpoint.com/newprofilewithemail",  "headers": {    "X-Authorization": "Lkjvlknqdjd54DOJF$",    "X-Origin": "actito-webhooks"  },  "isActive": true}

Reserved Content-type header

As Actito will POST the webhook event to the endpoint as an application/json body, you can't provide the Content-type header in your webhook subscription (provided one will be ignored).

Push mode

To be able to manage great loads, ACTITO allows you to define weither the event pushes should be made "One by one" or in "Bulk" mode.

This mode can be set when defining a new webhook subscription. If "Bulk" is choosen, each HTTP POST call will contain an array of events instead of a single one. The maximum amount of events that will be included in a single POST call can be customized by providing the "maxBlockSize" in the webhook subscription parameters.

{  "on": "PROFILE_TABLE",  "eventType": "CREATE",  "onElementId": "123456",  "onFields": [    "emailAddress"  ],  "targetUrl": "https://myactitowebhookendpoint.com/newprofilewithemail",  "headers": {    "X-Authorization": "Lkjvlknqdjd54DOJF$",    "X-Origin": "actito-webhooks"  },  "webhookPushType": "BULK",  "maxBlockSize": 100,  "isActive": true}

Payloads

The posted JSON payload will contain the data of the triggered event.
These data can be for instance the updated attributes of a profile, the id and the status of an etl execution etc.

Depending on the push mode of the webhook (ONE_BY_ONE or BULK), following kind of json will be sent in the HTTP request body :

One by one: (considering that the profile with id 125 has been created with an emailAddress)

{  "id": "2e629410-0652-449f-b9e6-86f04973ee7f",  "data": {    "profileId": 125,    "emailAddress": "john.smith@actito.com",    "_links": {      "profile": {        "href": "https://api.actito.com/ActitoWebServices/ws/v4/entity/MyEntity/table/Customers/profile/123456"      }    }  },  "_links": {    "webhook": {      "href": "https://api.actito.com/ActitoWebServices/ws/v4/entity/MyEntity/webhookSubscription/123456789"    }  }}

Bulk: (considering that twow profile with id 125 and 126 have been created with an emailAddress)

{  "id": "d7ab32ee-e36d-4feb-8a14-bf55df768722",  "data": [    {      "profileId": 125,      "emailAddress": "john.smith@actito.com",      "_links": {        "profile": {          "href": "https://api.actito.com/ActitoWebServices/ws/v4/entity/MyEntity/table/Customers/profile/123456"        }      }    },    {      "profileId": 126,      "emailAddress": "jane.smith@actito.com",      "_links": {        "profile": {          "href": "https://api.actito.com/ActitoWebServices/ws/v4/entity/MyEntity/table/Customers/profile/123457"        }      }    }  ],  "_links": {    "webhook": {      "href": "https://api.actito.com/ActitoWebServices/ws/v4/entity/MyEntity/webhookSubscription/123456789"    }  }}

Payload versions

ACTITO will compose the payload of the event pushes regarding the version of the payload you specified when creating your webhook.
Check the Events section for a full description of every versions available for which event type.

Expected response

ACTITO expects to receive a 2XX HTTP status code (200 OK, 201 Created, 202 Accepted or 204 No Content should be fine).

Any other response will be considered as a fail for the push.

Ordering and retries

ACTITO does not guarantee that events are pushed in the exact same order as it occured in ACTITO.

We currently make only retries after receiving 502 or 503 http status codes to allow potential network short interruptions (maintenance). In that case, we try a maximum of 5 times with 1 second between each try. This retry is blocking, so as to say.

Errors management

Every failed push is logged. You can have access to those fails by calling the API route for daily errors file download. In these files, each line represents a failed push with content, timing and encountered fail reason.

Response delay and timeouts

When posting to your endpoint, ACTITO expect a rather quick response.
A response delay under 100ms should be fine, depending on the number of events triggered each day, and on the dispatching of those events all along the day.

If the process triggered behind the endpoint is heavy, you should set up some kind of asynchronous process not to have to wait until end of processing before sending the endpoint response to ACTITO.

In any case, ACTITO will hang out if no response received within a second.