Utiliser les Webhooks

L'utilisation des Webhooks se fait par le biais d'abonnements. La création et la gestion de ces abonnements se fait via les APIs d'ACTITO.

S'abonner à un Webhook

Dans la catégorie "webhook-controller", une même opération est disponible pour créer un abonnement Webhook, quel que soit le type de table écouté.

images/download/attachments/615293557/image2019-10-30_9-20-14.png

Les paramètres à renseigner sont :

  • Le nom de l'entité sur laquelle la table est enregistrée

  • Le corps de la requête "webhookSubscription" : Il correspond à la définition de l'abonnement Webhook sous forme de code JSON. Ce code doit inclure les éléments suivants :

"on"

Ce paramètre indique la nature de l'élément ACTITO écouté. Cet élément peut être :

  • PROFILE_TABLE : Une table de profils

  • CUSTOM_TABLE : Une table personnalisée du modèle de données.

"onElementId"

Ce paramètre doit être l'identifiant technique de la table (de profils ou personnalisée) pour laquelle vous voulez être notifié.

"eventType"

Ce paramètre indique le type d'événement écouté :

  • CREATE : Nouveau profil ou nouvelle ligne d'une table

  • DELETE : Suppression d’un profil ou d'une ligne d'une table

  • UPDATE : Modification d’un profil ou d'une ligne d’une table

  • UPDATED_SEGMENT : Changement au niveau d’un segment (uniquement pour une table de profil)

  • UPDATED_SUBSCRIPTION : Changement au niveau d’un abonnement (uniquement pour une table de profil)

Il est nécessaire de créer un abonnement Webhook pour chaque type d'événement pour lesquels vous voulez recevoir des notifications.

"isActive"

Il s'agit d'un booléen qui indique si l’abonnement au Webhook est actif. Tant qu'il est actif, les événements correspondant aux paramètres du Webhook seront effectivement postés sur l’URL renseignée.

Une opération spécifique pourra servir à activer et désactiver les Webhooks existants.

"onFields"

Le paramètre"onFields" renseigne la liste des champs à écouter pour une table de profils ou une table de données. Ce paramètre a deux utilités :

D'une part, les champs listés apparaîtront dans le contenu de l'événement renvoyé par le Webhook vers l'URL renseignée.

D'autre part, ces champs restreignent le déclenchement de l’événement. Seuls les événements ayant un impact sur minimum un des champs listés seront pris en compte. En fonction du type d’événement, l’information sera obligatoire ou pas :

  • CREATE : Non-obligatoire. Si rien n’est mentionné, chaque création sera prise en compte et seules les informations techniques seront postées sur l'URL. Si une liste est mentionnée, par exemple ["emailAddress", "gsmNumber"], seules les nouvelles entrées ayant une valeur pour un de ces deux champs seront postées sur l'URL du Webhook. Seuls les attributs de profil ou les champs de table personnalisée peuvent être écoutés via cette méthode, pas les abonnements ni les segmentations.

  • DELETE : Non-obligatoire. Si rien n’est mentionné, chaque suppression sera prise en compte. Si une liste est mentionnée, par exemple ["emailAddress", "gsmNumber"], seules les nouvelles entrées ayant une valeur pour un de ces deux champs seront postées sur l'URL du Webhook.

  • UPDATE : Obligatoire. Il faut préciser la liste des champs écoutés, par exemple ["emailAddress", "gsmNumber"]. Seules les mises à jour d'entrées lors desquelles la valeur d'un des champs mentionnés a été modifiée seront prises en compte. Seuls les attributs de profil ou les champs de table personnalisée peuvent être écoutés via cette méthode, pas les abonnements ni les segmentations.

  • UPDATED_SEGMENT : Obligatoire. Il faut préciser la liste des segmentations écoutées, par exemple ["typeClient", "segmentationSimple"]. Seuls les profils ayant subi une modification au niveau d'une de ces segmentations seront pris en compte. Seules des segmentations peuvent être écoutées via cette méthode, pas les attributs de profils.

  • UPDATED_SUBSCRIPTION : Obligatoire. Il faut préciser la liste des abonnements écoutés, par exemple ["Newsletter", "Global"]. Seuls les profils concernés par un abonnement/désabonnement pour un de ces abonnements seront pris en compte. Seuls des abonnement peuvent être écoutés via cette méthode, pas les attributs de profils.

Remarques

  • Les champs visés par le Webhook ne peuvent être que des attributs de profil, des abonnements, des segmentations ou des champs de table de données. Les attributs techniques ne peuvent pas être pris en considération.

  • Il est nécessaire de renseigner le nom exact (sensible à la casse) de l'attribut de profil ou du champ de la table, sinon vous obtiendrez une erreur.

  • Dans le cas des segmentations et des abonnements, il suffit de renseigner leur nom.

"targetUrl"

Le paramètre "targetUrl" correspond à l’URL de votre choix sur laquelle seront postés les événements.

"headers"

Ce paramètre permet de passer des en-têtes de requête additionnelle, notamment pour de l'authentification nécessaire pour accéder à l'URL ciblée.

"webhookPushType"

Ce paramètre indique le mode utilisé pour pousser les événements. Il peut être :

  • ONE_BY_ONE : chaque appel contiendra un seul événement.

  • BULK : chaque appel compilera un ensemble d'événements, dont le nombre sera au plus la valeur spécifiée dans le paramètre "maxBlockSize"

"maxBlockSize"

Si le Webhook est en mode BULK, spécifie le nombre maximum d'événements que chaque appel pourra contenir (nombre entier entre 10 et 1000).

Il s'agit bien du nombre maximum, pas du nombre attendu avant de déclencher une notification : si la valeur du "maxBlockSize" n'est pas atteinte, l'appel sera envoyé après 5 secondes.

Exemple de mise en place d'abonnement Webhook pour les créations dans une table de profil en écoutant l'attribut "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
}

La réponse à une opération de création d'abonnement Webhook est uniquement son identifiant, qui doit être utilisé comme paramètre pour les opérations de mise à jour et de suppression de cet abonnement.

Structure des éléments obtenus

Les événements transmis sur l'adresse URL renseignée auront toujours une structure particulière, qui variera selon le type d’événement écouté.

Pour chaque événement, 3 types d'information peuvent être renseignés :

Informations techniques

L'événement aura toujours les informations suivantes :

  • "id" : Le premier paramètre "id" correspond à l'identifiant technique de l'abonnement

  • "tableId" : Il s'agit de l' identifiant technique de la table de profils ou de données

  • "profileId" : Ceci est l'identifiant technique du profil affecté ou du profil lié à l’interaction de la table de données

  • "eventType" : Ceci indique le type d’événement écouté

  • "tableType" : Ceci indique le type de table écoutée : table de profils ou de données

  • "businessKey" : Il s'agit de l'attribut unique défini techniquement comme la clé business de la table de profils

Informations sur les champs écoutés

La structure de l'événement va comporter une information pour chaque champ demandé dans le paramètre "onFields" lors de la création de l'abonnement Webhook. Cette information se retrouve dans l'ensemble "data". Elle se présente comme le nom de l'attribut ou du champ de la table couplé avec la valeur prise par celui-ci pour l'événement déclencheur.

Le paramètre "id" figurant dans l'ensemble "data" correspond à l'identifiant technique de l'événement.

Si un champ n’a pas de valeur, il apparaîtra dans la section "fields".

Astuce

Seuls les champs renseignés dans le paramètre "onFields" seront récupérés par le Webhook. Il convient donc de bien définir les champs qui vous intéressent dès la création de l'abonnement Webhook.

Informations RGPD

Ces informations n'apparaîtront que pour les événements liés à une table de profils. Elles seront remplies automatiquement et vous renseignent sur la provenance de l’événement et des données qui s'y rapportent.

Conserver ces informations pour pouvoir justifier la provenance des interactions de profil (notamment les abonnements) constitue une bonne pratique au niveau du RGPD.

Il s'agit de :

  • "dataCollectionSource" : La source de collecte de l’information. Il s’agit du biais par lequel ACTITO a recensé l’information.

  • "dataCollectionWay" : Le moyen de collecte de l’information. Cette donnée indique les informations techniques lié à l’appareil utilisé par le profil pour générer cette interaction.

  • "dataCollectionMoment" : Le moment de collecte de l’information. Il s’agit de la date et heure à laquelle ACTITO a enregistré l’information.