Travailler avec des webhooks
Introduction
Les webhooks vous permettent d'enregistrer une URL à laquelle nous vous notifierons chaque fois qu'un événement se produit dans votre compte. Lorsque l'événement se produit - par exemple, lorsqu'un abonnement réussi est créé, Rokt Calendar crée un objet Événement. Cet objet contient toutes les informations pertinentes sur l'événement, y compris le type d'événement et les données associées à cet événement. Rokt Calendar envoie ensuite l'objet Événement à toutes les URL définies dans les paramètres des webhooks de votre compte via une requête HTTP POST.
Configuration des paramètres des webhooks
Les webhooks sont configurés dans la section des paramètres des webhooks du compte Rokt Calendar. En cliquant sur Ajouter un webhook, un formulaire s'affiche pour ajouter une nouvelle URL de point de terminaison pour recevoir les webhooks, ainsi que le(s) type(s) d'événement(s) auxquels vous souhaitez vous abonner.
Vous pouvez saisir n'importe quelle URL à laquelle vous souhaitez recevoir les événements, mais cela devrait être une page dédiée sur votre serveur, conformément aux instructions ci-dessous. Vous pouvez également choisir d'être notifié de plusieurs types d'événements, ou seulement de certains.
Types d'événements d'abonnement
- Événement d'abonnement: Un utilisateur s'abonne à un calendrier.
- Événement de désabonnement: Un utilisateur se désabonne d'un calendrier.
Webhook v1 est obsolète. L'ancienne version de webhook ne prend en charge que 2 types d'événements de base. Veuillez utiliser Webhook v2 pour plus de types d'événements avec la dernière structure de charge utile des données.
Erreurs courantes de webhook
- Fournir une URL incorrecte dans le tableau de bord.
- Le point de terminaison du webhook ne renvoie pas un code d'état 200.
Réception d'une notification de webhook
La création d'un point de terminaison de webhook sur votre serveur ne diffère en rien de la création de n'importe quelle page sur votre site web. Les données du webhook sont envoyées au format JSON dans le corps de la requête POST. Tous les détails de l'événement sont inclus et peuvent être utilisés directement après avoir analysé le JSON en un objet Événement.
Réponse à un webhook
Pour accuser réception d'un webhook, votre point de terminaison doit renvoyer un code d'état HTTP 2xx. Toutes les autres informations renvoyées dans les en-têtes de la requête ou le corps de la requête sont ignorées. Tous les codes de réponse en dehors de cette plage, y compris les codes 3xx, indiqueront à Rokt Calendar que vous n'avez pas reçu le webhook. Cela signifie qu'une redirection d'URL ou une réponse "Non modifiée" sera considérée comme un échec.
Si un webhook n'est pas reçu avec succès pour une raison quelconque, Rokt Calendar continuera d'essayer d'envoyer le webhook pendant 30 minutes avec quelques minutes d'intervalle entre chaque tentative.
Lorsque vous consultez les informations spécifiques d'un événement via le tableau de bord, vous pouvez vérifier combien de fois nous avons tenté d'envoyer un événement à un point de terminaison en cliquant sur cette URL de point de terminaison dans la section Détails du webhook. Cela vous montrera la dernière réponse que nous avons reçue de votre point de terminaison, ainsi qu'une liste de tous les webhooks tentés et les codes d'état HTTP respectifs que nous avons reçus. Tout événement échoué peut également être réessayé depuis le tableau de bord après l'expiration des 30 minutes.
Meilleure pratique
Avant de passer en direct, testez que votre webhook fonctionne correctement. Vous pouvez le faire en envoyant des événements de test factices à partir du volet des paramètres des webhooks. Veuillez noter que ces événements de test factices ne seront pas associés à des objets réels dans votre compte.
Si votre script de webhook effectue une logique complexe ou effectue des appels réseau, il est possible que le script dépasse le délai d'expiration avant que Rokt Calendar ne voie son exécution complète. Pour cette raison, vous voudrez peut-être que votre point de terminaison de webhook confirme immédiatement la réception en renvoyant un code d'état HTTP 2xx, puis effectue le reste de ses tâches.
Les points de terminaison de webhook peuvent parfois recevoir le même événement plusieurs fois. Nous vous conseillons de vous prémunir contre les reçus d'événements en double en rendant votre traitement d'événements idempotent. Une façon de faire cela est de consigner les événements que vous avez traités, puis de ne pas traiter les événements déjà consignés.