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.

Webhooks sur les tables de données

S'abonner à un Webhook

Passons en revue les concepts à comprendre pour mettre en place un webhook relatif aux données de vos tables :

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

L'identifiant technique de la table (de profil ou personnalisée) pour laquelle vous ovulez recevoir des notifications est spécifié dans le paramètre "onElementId".

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

A savoir

Pour les tables personnalisées du modèle en étoile, il est nécessaire que les événements soient précisés dans le fichier JSON de définition de la table (dans le paramètre "eventToTrigger").
Un événement CREATE existe toujours par défaut dans les tables personnalisées, mais les événements d'UPDATE doivent être définis (notamment pour définir les mises à jour de quels champs déclenchent un événement).
N'hésitez pas à contacter votre gestionnaire de compte si vous avez besoin d'aide pour mettre en place des événements dans vos tables.

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

Notes

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

Astuce

Les webhooks de masse restent des appels en temps réel, particulièrement utils quand beaucoup d'événements (créations, MAJs) sont enregistrées en même temps. Mais les événements ne sont pas mis en queue jusqu'à atteindre le "maxBlockSize". Quand un événement est enregistré, il sera poussé unitairement si un autre événement n'est pas poussé d'ici quelques secondes.

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

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.

Astuce

Pour plus d'informations concernant le contenu des notifications webhooks, veuillez consulter le Developers Portal.