Skip to main content

Using Webhooks

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

Data tables webhooks​

Subscribing to a Webhook​

Let's review the business concepts that you need to understand when you set up a webhook related to your data tables:

"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

The technical id of the (profile or custom) table for which you want to receive notifications must be provided in the "onElementId" parameter.

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

Good to know

For custom tables, events must be defined in the JSON definition file of the custom table (in the "eventsToTrigger" parameter).
A CREATE event always exists by default in custom tables, but UPDATE events must be defined (notably to define updates on which fields trigger the event).
Do not hesitate to contact your account manager if you need help to set up events in your tables.

"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.
tip

Bulk webhook pushes remain real time events, especially useful when lots of events (creates, updates) happen at the same time. But events are not queued until reaching the "maxBlockSize".
When 1 event is recorded, this single event will be pushed immediately if another event is not recorded in a matter of seconds.

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

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

For more information regarding the payload of the webhook notifications, please see the developers portal .