Comprendre les webhooks dans Advanced KDP

Objectif de cet article

Découvrez les webhooks et la manière dont vous pouvez les utiliser pour envoyer des informations à vos applications tierces en réponse à des événements enregistrés dans Klaviyo. Pour découvrir comment recevoir des webhooks, consultez nos ressources pour développeurs sur l’utilisation des webhooks.

This content requires Functional cookies to be enabled.

Update Cookie Settings

Qu’est-ce qu’un webhook ?

Les webhooks permettent à Klaviyo de transmettre des informations ou « d’appeler » d’autres applications, outils et serveurs via des requêtes HTTP. Ils peuvent envoyer des informations sur un événement qui s’est produit (p. ex., une commande passée, un nouveau client qui s’est abonné, etc.) ou informer vos systèmes externes que l’événement s’est produit.

Klaviyo prend en charge 2 types de webhooks :

1. Webhooks dans Advanced KDP
   Les webhooks disponibles dans Advanced KDP sont utilisés pour notifier à vos systèmes externes qu’un événement particulier s’est produit, et vous permettent d’envoyer des informations en réponse à un large éventail d’événements sans les limitations d’un flux.
2. Webhooks de flux
   Les webhooks de flux sont des actions au sein des flux. Ils envoient des données lorsqu’un profil atteint l’action webhook, et peuvent inclure des informations sur ce profil ou sur l’événement qui a déclenché le flux.

Composants clés des webhooks

Les webhooks se composent de quelques éléments clés :

• Sujet
  L’événement qui déclenche un webhook.
• Corps (ou « la charge utile »)
  Les données envoyées par le webhook.
• En-tête
  L’emplacement pour transmettre des informations supplémentaires (d’authentification, par exemple).

En quoi les webhooks dans Advanced KDP diffèrent-ils des webhooks de flux ?

Selon vos besoins, vous pouvez utiliser des webhooks dans Advanced KDP ou des webhooks de flux.

Événements inclus

Dans les flux déclenchés par un indicateur, les webhooks de flux ne peuvent répondre qu’aux événements pris en charge en tant que déclencheurs de flux. Par exemple, Received Email et Clicked Email ne sont pas disponibles dans le sélecteur de déclencheur d’indicateur, tandis que se désabonner du marketing par e-mail est pris en charge. Les webhooks système dans Advanced Klaviyo Data Platform vous permettent de sélectionner des sujets pour les événements liés aux messages, ainsi que des événements provenant des intégrations et des API de Klaviyo.

En voici quelques exemples :

• Événements liés aux e-mails (par exemple, E-mail reçu, E-mail cliqué, E-mail marqué comme spam, se désabonner du marketing par e-mail)
• Événements liés aux SMS (par exemple, SMS Envoyé, SMS Reçu)
• Événements liés aux notifications push (par exemple, Push Reçue, Rebond de Push)
• Événements provenant d’intégrations (c’est-à-dire les événements provenant d’intégrations first-party créées par Klaviyo)
• Événements d’API (par exemple, les événements synchronisés via les API de Klaviyo).

Charge utile

Les webhooks de flux vous permettent de personnaliser les données de requête en configurant un corps JSON. Les webhooks système dans Advanced Klaviyo Data Platform utilisent une charge utile prédéfinie contenant des données sur les événements qui se sont produits. Une seule requête peut inclure plusieurs événements provenant des sujets que vous avez sélectionnés.

Limitations du flux

Les webhooks de flux suivent le déclencheur et les étapes du flux qui les contient. Utilisez des flux distincts pour répondre à différents déclencheurs de flux. L’action webhook doit être Live pour envoyer des requêtes automatiquement ; une action en Draft n’envoie pas de requêtes. Les webhooks système s’exécutent en dehors des flux et peuvent s’abonner à plusieurs sujets sur 1 point de terminaison.

Configurer un webhook

1. Accédez à Gestion des données > Webhooks dans Klaviyo.
2. Cliquez sur Créer un webhook.
3. Sur la page Créer un webhook, saisissez les informations suivantes :
   • Nom
     Comment vous identifierez votre webhook.
   • URL du point de terminaison
     L’URL associée à la destination de la demande de webhook.
   • Clé secrète
     Saisissez une clé secrète de 16–100 caractères. Klaviyo utilise cette clé pour signer les requêtes, afin que votre application de réception puisse vérifier qu’elles proviennent de Klaviyo.
   • Description
     Une description optionnelle de votre webhook.
4. Sous Sujets, sélectionnez 1 ou plusieurs sujets qui doivent déclencher des notifications. Par exemple, event:klaviyo.received_email correspond à E-mail reçu.

5. Facultatif : testez la connexion en suivant les étapes de la section Tester les webhooks système ci-dessous avant d’enregistrer.
6. Cliquez sur Enregistrer pour créer le webhook. Klaviyo vous renvoie à la page Webhooks.

Après l’enregistrement, votre webhook apparaît sur la page Webhooks avec les détails suivants :

• Nom du webhook ;
• URL des points de terminaison (raccourcie pour des raisons de sécurité)
• Statut

Pour arrêter l’envoi de notifications, ouvrez le menu à côté du webhook, puis sélectionnez Désactiver. Pour le supprimer, sélectionnez Supprimer, puis confirmez la suppression.

Tester des webhooks système

1. Après avoir rempli les champs obligatoires sur la page Créer un webhook et sélectionné vos sujets, cliquez sur Tester la connexion.

2. Dans le panneau Tester le webhook, sélectionnez un sujet sous Sujets, puis cliquez sur Tester pour envoyer un exemple de requête à l’URL de votre point de terminaison.

3. Consultez le message indiquant si le test a réussi. L’onglet Requête affiche les en-têtes et la charge utile envoyés à vos points de terminaison. L’onglet Réponse affiche les en-têtes de réponse, le corps, et le code d’état de vos points de terminaison.

1. Cliquez sur Annuler pour fermer le panneau de test et revenir à la configuration de votre webhook.

Exemple de charge utile

Vous trouverez ci-dessous un exemple de payload pour une demande déclenchée par un e-mail reçu (event:klaviyo.received_email).

{
  "meta": {
    "timestamp": "2023-08-10T07:25:23.700369+00:00",
    "klaviyo_webhook_id": "ID",
    "version": "2024-06-28",
    "klaviyo_payload_id": "3843971dcfdee5083e6289e1bbdbb003e538b5a8a668fc43ae4f19d415ac18a2",
    "klaviyo_account_id": "ACCOUNT_ID"
  },
  "data": [
    {
      "topic": "event:klaviyo.received_email",
      "external_id": "ID",
      "payload": {
        "data": {
          "id": "ID",
          "type": "event",
          "links": {
            "self": "https://a.klaviyo.com/api/events/ID/"
          },
          "attributes": {
            "uuid": "96150200-374e-11ee-8001-a163313bc6c2",
            "datetime": "2023-08-10 07:21:56+00:00",
            "timestamp": 1691652116,
            "event_properties": {
              "$ESP": 0,
              "Subject": "? Free (Cool!) Swag Alert ?",
              "$message": "01H7F525FKR31P27Y7PNGVBBKK",
              "$event_id": "01H7F525FKR31P27Y7PNGVBBKK:125423419905414052533228990613763937641",
              "$group_ids": [
                "V7adxq"
              ],
              "$attribution": {
                "$send_ts": 0,
                "$attributed_event_id": ""
              },
              "Email Domain": "klaviyo-demo.com",
              "Campaign Name": "Daily Newsletter: 2023-08-10",
              "Inbox Provider": "Amazon SES Inbound",
              "$_cohort$message_send_cohort": "1691652081:01H7F525FKR31P27Y7PNGVBBKK"
            }
          },
          "relationships": {
            "metric": {
              "data": {
                "id": "ID",
                "type": "metric"
              },
              "links": {
                "self": "https://a.klaviyo.com/api/events/ID/relationships/metric/",
                "related": "https://a.klaviyo.com/api/events/ID/metric/"
              }
            },
            "profile": {
              "data": {
                "id": "ID",
                "type": "profile"
              },
              "links": {
                "self": "https://a.klaviyo.com/api/events/ID/relationships/profile/",
                "related": "https://a.klaviyo.com/api/events/ID/profile/"
              }
            }
          }
        }
      }
    }
  ]
}

Ressources supplémentaires