Using Webhooks is done via subscriptions. Creating and managing these subscriptions is done through the ACTITO APIs.

Subscribing to a Webhook

In the "webhook-controller" category, the same operation can be used to create a Webhook subscription for both types of table.

images/download/attachments/615293577/image2019-10-30_11-4-3.png

The following parameters will need to be provided:

The name of the entity on which the table is stored
The "webhookSubscription" body: This is the definition of the Webhook subscription as JSON code. This mode must include the following elements:

"on"

This parameter specifies the nature of the ACTITO element to which the Webhook listens. This element can be:

PROFILE_TABLE: For a profile table
CUSTOM_TABLE: For additional custom tables of the data model

This parameter must be the technical id of the (profile or custom) table for which you want to receive notifications.

"eventType"

This parameter specifies the type of event to which you are listening:

CREATE: New profile or new table entry
DELETE: Deletion of a profile or of a table entry
UPDATE: Modification of a profile or of a table entry
UPDATED_SEGMENT: Modification in relation to a segment (only for a profile table)
UPDATED_SUBSCRIPTION: Modification in relation to a subscription (only for a profile table)

It is necessary to create a Webhook subscription for each type of event for which you want to receive notifications.

"isActive"

This is a boolean which indicates whether a Webhook subscription is active. As long as it is active, events that match the Webhook parameters will be effectively posted on the given URL.

A specific operation can be used to activate and deactivate existing Webhooks.

"on Fields"

The "onFields parameters specifies the list of fields of your profile or custom table to which you will be listening. There are two uses to this parameter:

On the one hand, all fields listed there will appear in the content of the event submitted by the Webhook to the given URL.

On the other hand, these fields restrict the event trigger. Only events impacting at least one of the fields listed there will be taken into account. Depending on the event type, this information may be mandatory or not:

CREATE: Optional. Should nothing be specified, every creation will be taken into account and only technical information will be posted on the URL. If a list is specified, such as ["emailAddress", "gsmNumber"], only new entries that contain a value for one of the two fields will be posted on the Webhook URL. You can only listen to profile attributes or custom table fields via this method, not to subscriptions or segmentations.
DELETE: Optional. Should nothing be specified, every deletion will be taken into account and only technical information will be posted on the URL. If a list is specified, such as ["emailAddress", "gsmNumber"], only new entries that contain a value for one of the two fields will be posted on the Webhook URL.
UPDATE: Mandatory. You will need to specify the list of fields to which you are listening, for example ["emailAddress", "gsmNumber"]. Only entry updates for which the value of one of the specified fields was modified will be posted on the Webhook URL. You can only listen to profile attributes or custom table fields via this method, not to subscriptions or segmentations.
UPDATE_SEGMENT: Mandatory. You will need to specify the list of segmentations to which you are listening, for example ["clientType", "simpleSegmentation"]. Only profiles with a modification on one of these segmentations will be posted on the Webhook URL. You can only listen to segmentations via this method, not to profile attributes.
UPDATED_SUBSCRIPTION: Mandatory. You will need to specify the list of subscription to which you are listening, for example ["Newsletter", "Global"]. Only profiles who subscribed or unsubscribed to one of these subscriptions will be posted on the Webhook URL. You can only listen to subscriptions via this method, not to profile attributes.

Notes

Fields targeted by the Webhook can only be profile attributes, subscriptions, segmentations or custom table fields. Technical attributes cannot be taken into consideration.
It is necessary to provide the exact name (case sensitive) of the profile attribute or of the table field, otherwise you will get an error message.
In the case of segmentations and subscription, you only need to provide their name.

"targetUrl"

The "targetUrl" parameter is the URL you chose and on which the events will be posted.

"headers"

This parameter can be used to push additional request headers, such as authentication required to access the URL endpoint.

"webhookPushType"

This parameter specifies the mode used to push events. It can be:

ONE_BY_ONE: each call will contain a single event.
BULK: each call will compose a payload of several events, the maximum number of which will be the value of the "maxBlockSize" parameter.

"maxBlockSize"

If the Webhook is in BULK mode, specifies the maximum number of events that a call can contain (integer between 10 and 1000).

This is indeed the maximum number, not the number expected before triggering a notification: if the "maxBlockSize" value is not reached, the call will be sent after 5 seconds.

Example of Webhook subscription for creations in a profile table while listening to the attribute "emailAddress:

POST/entity/e}/webhookSubscription

Curl call

                    curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" -d "{
                  
                     "on": "PROFILE_TABLE",
                  
                     "onElementId": "123456",
                  
                     "eventType": "CREATE",
                  
                     "onFields": [
                  
                     "emailAddress"
                  
 ],

                     "targetUrl": "https://myactitowebhookendpoint.com/newprofilewithemail",
                  
                     "headers": {
                  
                     "X-Authorization": "Lkjvlknqdjd54DOJF$"
                  
 },

                     "webhookPushType": "BULK",
                  
                     "maxBlockSize": 100,
                  
                     "isActive": true
                  
                    } "https://test.actito.be/ActitoWebServices/ws/v4/entity/actito/webhookSubscription"
                  
                    Response body
                  
{

                     "id": 15
                  
}

The answer to a Webhook subscription creation is only its id, which will be used as parameter for update and deletion operations about this subscription.

Structure of obtained elements

Events posted to the given URL address will always have a specific structure, which will vary according to type of events to which you are listening.

For each event, 3 information types can be posted:

Technical information

The event will always contain the following information:

"id": The first "id" parameter is the technical id of the subscription
"tableId": Technical id of the profile or custom table
"profileId": Technical id of the affected profile or of the profile related to the custom table interaction
"eventType": Specifies the type of event to which you are listening
"tableType": Specifies the type of table to which you are listening: profile or custom table
"businessKey": Unique attribute technically defined as the business key of the profile table

Information about listened fields

The structure of the event will include information about each field indicated in the "onFields" parameters while creating the Webhook subscription. This info is found in the "data" array. It is displayed as the name of the attribute or of the custom table field paired with its value for the trigger event.

The "id" parameter contained in the "data" array is the technical id of the event.

If a field does not have any value, it will appear in the "fields" section.

Tip

The Webhook will only retrieve fields specified in the "onFields" parameter. It is therefore necessary to correctly define the fields in which you are interested as soon as you create the Webhook subscription.

GDPR information

This information will only appear for events related to a profile table. They will be automatically filled in and will provide you with information about the origin of the event and of the data related to it.

Storing this information will enable you to justify the origin of profile interactions (especially for subscriptions), which is a good GDPR practice.

It is made of:

"dataCollectionSource": The origin of the information collection, from which ACTITO obtained the information.
"dataCollectionWay": How the information was collected. This data includes technical information related to the device used to generate this information.
"dataCollectionMoment": The moment of the information collection. This is the date and time at which ACTITO stored the information.