Recevoir des notifications d'événements au sein d’une organisation Omny Studio
Les webhooks permettent à vos services de recevoir des requêtes HTTP POST vous signalant des événements pertinents tels que la création d'un clip ou la mise à jour d'un programme.
Souscrire et gérer des abonnements à des webhooks
Vous pouvez définir plusieurs abonnements à des webhooks à partir de la page « Webhooks » de vos « Organization settings » ou au niveau du réseau sous « Network settings - Webhooks », comme le montre cette capture d'écran :
Vous devrez saisir l'URL de votre terminal de réception et choisir les événements pour lesquels vous souhaitez recevoir des notifications.
Une fois que vous aurez configuré un abonnement et l'aurez activé, les événements auxquels vous vous êtes abonné commenceront à être envoyés vers ce terminal.
La page d’abonnement au webhook comporte également les informations détaillées des événements envoyés. Les 100 événements les plus récents s'affichent par défaut, et comprennent la requête et la réponse dans leur intégralité. Vous pouvez également filtrer cette liste pour faire apparaître les défaillances récentes ou des types d’événements spécifiques.
Détails techniques de la mise en œuvre
Corps de la requête de webhook
Le corps de la requête du webhook est un objet JSON ayant les propriétés suivantes :
Type(chaîne de caractères) - le type d’événement qui a provoqué le déclenchement du webhook. Cette propriété est structurée comme suit :{entity}{change-type}, par exempleProgramCreated,ClipDeleted, etc.Timestamp(chaîne) - l’heure à laquelle l’événement s’est produit (à la seconde près)ChangeId(Guid) : un GUID représentant cette modification unique. Cet identifiant sera commun à plusieurs abonnés pour le même événement.EventId(Guid) : un GUID représentant cet événement unique pour un abonné donné.Current(objet) : la représentation de l’entité au moment où l’événement s’est produit. Le modèle courant varie en fonction du type d'événement. Les événements de type clip envoient un modèle de clip, les événements de type playlist un modèle de liste de lecture et les événements de type programme un modèle de programme. Les modèles correspondent à ce que l’API de gestion utilise pour chacune de ces entités.
Voici un exemple de requête :
{
"Type": "ClipDeleted",
"Timestamp": "2019-10-09T10:25:56",
"Current": { ... }
}Délai d'envoi de l’événement
Un léger délai peut s'écouler entre le moment où les actions se produisent et celui où les événements de webhook sont envoyés. En moyenne, cet envoi peut prendre entre 30 et 60 secondes.
Ce délai varie en fonction du nombre d'abonnements aux webhooks actifs, de la liste des événements à envoyer et du temps de réponse du (des) serveur(s) recevant les webhooks.
Bien que nous fassions généralement tout notre possible pour envoyer les webhooks dans l'ordre indiqué, le client doit prévoir la possibilité de recevoir des événements dans le désordre. Parfois, les tentatives répétées peuvent entraîner l'envoi d'un événement antérieur à la suite d'événements plus récents. Vous pouvez vérifier la propriété Timestamp pour savoir quand l'événement s'est initialement produit.
Erreurs de transmission d'un d’événement
Toute réponse comportant un code de statut HTTP non valide (par exemple, différent de 2XX) sera considérée comme une erreur et la transmission de l'événement sera réitérée. Nous réessayerons de délivrer le message jusqu'à 5 fois avec un intervalle exponentiel entre les tentatives pouvant aller jusqu'à 60 minutes.
Si un événement est toujours considéré comme erroné après le 5e essai, l'événement du webhook échouera définitivement et ne pourra être retransmis. Si dix messages consécutifs sont rejetés, l'abonnement au webhook sera désactivé et tous les événements en attente pour cet abonnement seront marqués comme ayant échoué de façon permanente. Une notification par courrier électronique sera adressée au « contact technique de l'organisation » lors de la désactivation de l'abonnement au webhook. L'abonnement pourra être réactivé manuellement si vous souhaitez continuer à recevoir des événements. Notez que les événements survenus pendant que l'abonnement était inactif ne seront pas envoyés, même après réactivation de ce dernier.
Déduplication des événements
Bien que nous essayions généralement de dédupliquer les événements, il est possible que nous envoyions un événement plus d'une fois.
Les destinataires doivent vérifier la singularité de la demande à l'aide de l'en-tête HTTP X-Omny-Event-Id de la requête. Il s'agit de l'identifiant de la demande qui caractérise l'événement et permet d'établir une corrélation avec la tentative d'envoi de la requête.
Si vous contactez l'assistance, veuillez mentionner le X-Omny-Event-Id pour permettre l'identification de l'événement en question.
Sécurité
Afin de vous assurer que les messages que vous recevez ont bien été envoyés par Omny Studio, vous pouvez configurer une clé de confidentialité partagée pour vos abonnements aux webhooks, que vous pourrez vérifier à l'aide de l'en-tête HTTP X-Omny-Signature de la requête. Nous recommandons vivement l'utilisation de ce processus de certification afin de prévenir l'envoi par des acteurs malveillants de messages vers vos terminaux de réception de webhooks.
Le X-Omny-Signature Cette valeur de l'en-tête HTTP est générée à l'aide de la fonction de hachage HMAC-SHA256.
Key : la valeur secrète partagée
Value : le corps de la requête (encodage UTF-8, sans en-tête HTTP)
Vérifiez que le hachage généré, encodé en hexadécimal (sans le 0x de tête ajouté), correspond à la valeur fournie dans l'en-tête HTTP X-Omny-Signature de la demande que vous avez reçue.
Nous vous recommandons par ailleurs vivement d'utiliser le protocole HTTPS pour l'abonnement au webhook. Les événements envoyés à une URL HTTPS confirmeront que le certificat TLS est valide et signé par une autorité de confiance.