Configurer les webhooks

Déclarez un callback dans Studio, abonnez-le à des événements, authentifiez-le et vérifiez chaque livraison.

8 min de lecture

Dans cet exemple, Lindenhall envoie à son CRM chaque lot gagné, au moment même du gain : personne n'a besoin d'aller chercher les gains à intervalles réguliers. Vous faites toute la configuration vous-même, dans Paramètres de l'Entreprise > Webhooks.

Avant de commencer

  • Un compte administrateur dans Studio. L'onglet Webhooks n'apparaît que lorsque l'organisation Global est choisie dans le sélecteur d'organisation.
  • Un endpoint HTTPS public. Les URL en http simple et les hôtes qui se résolvent en adresse privée sont refusés.
  • Un endroit sûr pour stocker le secret de signature, qui ne s'affiche qu'une fois.
  • Des endpoints distincts pour le staging et la production, pour que le trafic de test n'atteigne jamais les systèmes en production.

Créer le callback

Dans le sélecteur d'organisation, choisissez Global, puis sélectionnez Paramètres Généraux. Ensuite :

  1. Sélectionnez l'onglet Webhooks.

    Paramètres de l'Entreprise avec l'onglet Webhooks mis en évidence

  2. Sélectionnez Nouveau webhook.

    Onglet Webhooks listant trois callbacks, avec le bouton Nouveau webhook mis en évidence

  3. Saisissez le Nom, ici Lindenhall CRM.

    Fenêtre Créer un webhook avec le nom Lindenhall CRM mis en évidence

    Un callback par système en aval permet d'isoler les pannes.

  4. Saisissez l'URL du endpoint, ici https://crm.lindenhall.example/omnilab/events.

    Fenêtre Créer un webhook avec l'URL du endpoint mise en évidence

  5. Laissez le champ Méthode HTTP sur POST, sauf si le système récepteur attend une autre méthode.

    Fenêtre Créer un webhook avec la méthode HTTP POST mise en évidence

  6. Sélectionnez Créer.

    Fenêtre Créer un webhook avec le bouton Créer mis en évidence

  7. Copiez le secret de signature dans votre stockage de secrets avant de fermer la fenêtre.

    Fenêtre Secret de signature, la valeur floutée ici, avec le bouton de copie mis en évidence

Si vous avez fermé la fenêtre sans le copier, renouvelez le secret de signature pour en obtenir un nouveau.

Abonner le callback à des événements

Un nouveau callback ne reçoit rien tant qu'il n'a pas au moins un abonnement. Dans l'onglet Webhooks :

  1. Sur la ligne du callback, sélectionnez Abonnements.

    Onglet Webhooks avec le bouton Abonnements mis en évidence sur la ligne CRM sync

  2. Sélectionnez Ajouter un abonnement.

    Onglet Abonnements de CRM sync avec le bouton Ajouter un abonnement mis en évidence

  3. Saisissez un Nom pour cette partie du trafic, ici CRM sync — reward wins only.

    Formulaire d'abonnement avec le nom CRM sync — reward wins only mis en évidence

  4. Dans le champ Types d'événements, sélectionnez les événements voulus, ici Gagné et Échangé(s).

    Types d'événements indiquant 2 sélectionnés, avec le sélecteur des événements de récompense ouvert, mis en évidence

    Le sélecteur regroupe les événements par famille, comme Point de contact, Récompense et Réservation et billet, et vous pouvez y lancer une recherche. Ne le laissez vide que si vous voulez tous les types d'événements : une liste vide vous abonne à tous.

  5. (Facultatif) Dans le champ Type d'événement personnalisé, saisissez un type que le sélecteur ne liste pas, ici submission.created.v1.

    Formulaire d'abonnement avec submission.created.v1 dans Type d'événement personnalisé, mis en évidence

  6. (Facultatif) Sélectionnez Ajouter un élément personnalisé.

    Formulaire d'abonnement avec le bouton Ajouter un élément personnalisé mis en évidence

    Le type s'ajoute au champ Types d'événements, avec un contour en pointillés. Copiez les noms depuis la référence des événements.

  7. (Facultatif) Pour limiter la livraison à une organisation, sélectionnez Ajouter un filtre.

    Formulaire d'abonnement avec le bouton Ajouter un filtre mis en évidence

  8. (Facultatif) Dans la nouvelle ligne de filtre, remplacez la clé tenant_id par group_id.

    Ligne de filtre avec la clé group_id mise en évidence

  9. (Facultatif) Saisissez l'ID de l'organisation comme valeur, ici groups/6946c01f-8542-471c-9e2f-dac2661027c6.

    Ligne de filtre avec un ID d'organisation comme valeur, mis en évidence

    Les filtres se combinent par un ET logique et doivent correspondre exactement. La section Correspondance des filtres indique à quels événements chaque clé correspond aujourd'hui.

  10. Sélectionnez Créer.

    Formulaire d'abonnement avec le bouton Créer mis en évidence

    L'abonnement apparaît dans la liste avec le statut Actif, accompagné de ses types d'événements et de ses filtres.

Le bouton Mettre en pause arrête la livraison sans perdre la configuration, et le bouton Reprendre la réactive.

Recevoir votre premier événement

Studio ne propose ni envoi de test ni journal des livraisons : les livraisons apparaissent donc dans le journal de votre propre récepteur. Ce récepteur Node.js vérifie chaque requête, ignore les doublons et répond immédiatement.

Il nécessite Node.js 18 ou supérieur, ainsi que le vérificateur présenté dans Vérifier la signature, enregistré sous verify.js dans le même dossier. Préparez le projet :

Terminal
npm init -y
npm pkg set type=module
npm install express
server.js
import express from "express";
import { isValidOmniLabSignature } from "./verify.js";

const signingSecret = process.env.OMNILAB_SIGNING_SECRET;
if (!signingSecret) {
  throw new Error("Set OMNILAB_SIGNING_SECRET to the callback's signing secret");
}

// En production, utilisez votre propre base de données : ce Set se vide à chaque redémarrage.
const handledIds = new Set();

const app = express();

// express.raw conserve les octets exacts couverts par la signature. Les événements peuvent atteindre 256 Ko.
app.post(
  "/omnilab/events",
  express.raw({ type: "*/*", limit: "1mb" }),
  (req, res) => {
    const webhookId = req.get("webhook-id");
    const webhookTimestamp = req.get("webhook-timestamp");
    const header = req.get("webhook-signature");
    const rawBody = Buffer.isBuffer(req.body) ? req.body.toString("utf8") : "";

    if (!webhookId || !webhookTimestamp || !header) {
      return res.status(400).send("Missing webhook headers");
    }
    const valid = isValidOmniLabSignature({
      header,
      webhookId,
      webhookTimestamp,
      rawBody,
      signingSecret,
    });
    if (!valid) {
      return res.status(400).send("Invalid signature");
    }

    // Une nouvelle tentative a le même webhook-id : accusez réception sans la traiter deux fois.
    if (handledIds.has(webhookId)) {
      return res.sendStatus(204);
    }

    let event;
    try {
      event = JSON.parse(rawBody);
    } catch {
      return res.status(400).send("Body is not JSON");
    }
    handledIds.add(webhookId);

    // Répondez avant tout traitement : la plateforme attend 30 secondes au maximum.
    res.sendStatus(204);

    // Transmettez ici l'événement à votre propre file d'attente. Cet exemple se contente de le journaliser.
    console.log(`Received ${event.type} (${event.id})`, event.data);
  },
);

app.listen(3000, () => {
  console.log("Listening on http://localhost:3000/omnilab/events");
});

Lancez-le avec le secret de signature que vous avez copié à la création du callback :

Terminal
OMNILAB_SIGNING_SECRET='<your signing secret>' node server.js

Le champ URL du endpoint du callback doit pointer vers ce serveur, en HTTPS public. Pendant le développement, placez un service de tunnel devant le port 3000. Saisissez ensuite l'adresse du tunnel, suivie de /omnilab/events, dans le champ URL du endpoint de l'onglet Général.

Pour envoyer un premier événement, jouez à une campagne publiée sur votre compte de staging et gagnez son lot. Le gain déclenche l'envoi de reward.won.v1, et le récepteur écrit son type et son ID dans le journal.

Un 4xx autre que 429 n'est jamais retenté : un récepteur qui répond 400 perd donc cet événement. Renvoyez un 5xx si vous voulez que la livraison soit retentée. Tous les cas sont détaillés dans Garanties de livraison.

S'authentifier auprès de votre endpoint

Si votre récepteur exige ses propres identifiants, attribuez un mode d'authentification au callback. Voici les champs demandés pour chaque mode :

ModeAdapté àCe que vous saisissez
AucunL'endpoint s'appuie uniquement sur la vérification de signatureRien
BasiqueLes endpoints qui attendent un nom d'utilisateur et un mot de passeNom d'utilisateur, puis Mot de passe sous Identifiants secrets
Jeton BearerLes services qui acceptent un jeton d'API statiqueNom d'en-tête personnalisé facultatif, puis Jeton Bearer sous Identifiants secrets. La valeur de l'en-tête est toujours Bearer <token>.
OAuth2 (identifiants client)Les plateformes qui émettent des jetons de courte duréeID client, Endpoint du jeton, Portées, Méthode d'authentification du client, Audience facultative, puis Secret client sous Identifiants secrets

Pour OAuth2, le champ Méthode d'authentification du client est obligatoire et n'accepte que deux valeurs. client_secret_basic envoie l'ID client et le secret dans un en-tête Authorization, et client_secret_post les envoie dans le corps de la requête de jeton. Toute autre valeur est refusée quand vous enregistrez.

Enregistrez le mode avant son secret : un secret n'est accepté que pour le mode déjà enregistré. Dans l'onglet Webhooks :

  1. Sur la ligne du callback, ici Analytics export, sélectionnez Modifier.

    Onglet Webhooks avec le bouton Modifier mis en évidence sur la ligne Analytics export

  2. Sélectionnez l'onglet Authentification.

    Analytics export avec l'onglet Authentification mis en évidence

  3. Dans le champ Mode, choisissez le mode qu'attend votre endpoint, ici OAuth2 (identifiants client).

    Onglet Authentification avec le mode OAuth2 (identifiants client) mis en évidence

  4. Saisissez l'ID client, ici lindenhall-analytics.

    Onglet Authentification avec l'ID client lindenhall-analytics mis en évidence

  5. Saisissez l'Endpoint du jeton, ici https://idp.lindenhall.example/oauth2/token.

    Onglet Authentification avec le champ Endpoint du jeton mis en évidence

  6. Saisissez les Portées, ici analytics.write.

    Onglet Authentification avec le champ Portées réglé sur analytics.write, mis en évidence

  7. Saisissez la Méthode d'authentification du client, ici client_secret_post.

    Onglet Authentification avec le champ Méthode d'authentification du client réglé sur client_secret_post, mis en évidence

  8. Sélectionnez Enregistrer l'authentification.

    Onglet Authentification avec le bouton Enregistrer l'authentification mis en évidence

  9. Sous Identifiants secrets, saisissez le mot de passe, le jeton ou le secret client.

    Identifiants secrets avec le champ Secret client mis en évidence

  10. Sélectionnez Enregistrer les secrets.

    Identifiants secrets avec le bouton Enregistrer les secrets mis en évidence

    Les secrets ne sont plus jamais affichés. Si vous laissez plus tard un champ de secret vide, la valeur enregistrée est conservée.

Renouveler le secret de signature

Après un renouvellement, chaque livraison est signée avec le nouveau secret et avec le précédent, jusqu'au renouvellement suivant. Un vérificateur qui utilise encore l'ancien secret continue de valider les requêtes : vous pouvez donc changer de secret sans perdre d'événements.

Retirer un secret divulgué demande deux renouvellements

Après un renouvellement, le secret divulgué signe encore chaque livraison en tant que secret précédent. Renouvelez deux fois pour qu'il ne signe plus rien, puis donnez à votre vérificateur le secret le plus récent.

Dans l'onglet Webhooks :

  1. Sur la ligne du callback, sélectionnez Modifier.

    Onglet Webhooks avec le bouton Modifier mis en évidence sur la ligne CRM sync

  2. Sélectionnez l'onglet Secrets.

    CRM sync avec l'onglet Secrets mis en évidence

  3. Sélectionnez Renouveler le secret de signature.

    Onglet Secrets avec le bouton Renouveler le secret de signature mis en évidence

  4. Confirmez le renouvellement dans la boîte de dialogue du navigateur.

    Le message annonce que les vérificateurs qui utilisent l'ancien secret échoueront immédiatement. En réalité, ils continuent de valider les requêtes jusqu'au renouvellement suivant.

  5. Copiez le secret de la fenêtre Nouveau secret de signature dans votre stockage de secrets.

    Fenêtre Nouveau secret de signature, la valeur floutée ici, avec le bouton de copie mis en évidence

  6. Mettez à jour votre vérificateur avec le nouveau secret.

L'onglet Secrets affiche aussi une Référence du secret. Elle identifie le secret dans les échanges avec le support, et ne permet ni de signer ni de vérifier quoi que ce soit.

Adapter la requête (facultatif)

La plupart des récepteurs acceptent l'événement tel qu'il est envoyé. Si le vôtre attend un autre format, utilisez l'onglet Transformation :

  • Méthode HTTP et Type de contenu : la méthode et le type de contenu de la requête sortante.
  • Modèle d'URL (facultatif) : remplace l'endpoint de l'onglet Général. Pratique pour diriger chaque type d'événement vers un chemin différent.
  • Modèle du corps (facultatif) : laissez-le vide pour envoyer le JSON brut de l'événement.
  • En-têtes personnalisés : envoyés à chaque livraison.

Les modèles font référence aux champs de l'événement avec {{event.<field>}}, et event.payload contient le champ data de l'événement :

Body template
{
  "eventId": "{{event.id}}",
  "eventType": "{{event.type}}",
  "rewardId": "{{event.payload.reward_id}}"
}

Un en-tête personnalisé nommé Authorization, Proxy-Authorization, webhook-id, webhook-timestamp ou webhook-signature, quelle que soit la casse, est refusé quand vous sélectionnez Enregistrer la transformation. Définissez plutôt les identifiants dans l'onglet Authentification. N'ajoutez pas non plus User-Agent : la plateforme définit le sien. La signature couvre le corps produit par votre modèle.

Surveiller l'état des livraisons

Chaque carte de callback affiche un badge de statut :

  • Vérifié : le statut normal. Un callback est créé avec le statut Vérifié et le garde tant qu'il accepte les livraisons. Ce statut ne signifie pas que du trafic a été testé.
  • En échec : votre endpoint a répondu 410 Gone. Dépliez la carte, ou ouvrez l'onglet Général, pour lire le motif de l'échec.

Une réponse 410 Gone arrête définitivement la livraison

410 Gone indique à la plateforme que l'endpoint est retiré. Le callback cesse de recevoir des événements, et rien dans Studio ne le réactive. Ne renvoyez 410 que si c'est bien votre intention. Si cela arrive par accident, créez un callback de remplacement et ajoutez de nouveau ses abonnements.

En cas de blocage

  • Le callback ne reçoit rien : vérifiez qu'il a un abonnement, que cet abonnement a le statut Actif, et que chaque type d'événement fait partie de ceux que la référence des événements indique comme envoyés. Un événement personnalisé mal orthographié est accepté sans avertissement et ne correspond jamais à aucun événement. Un filtre interaction_id ne correspond aujourd'hui à aucun événement.
  • Impossible d'enregistrer un abonnement : chaque filtre exige une clé et une valeur, et la clé doit être tenant_id, group_id ou interaction_id. Le champ de clé suggère aussi contact_id, qui est refusé.
  • Les vérifications de signature échouent désormais : le secret a été renouvelé deux fois depuis la dernière mise à jour de votre vérificateur, ou le corps a été analysé avant la vérification. Utilisez le secret le plus récent et le corps brut.
  • Les livraisons se sont arrêtées après un incident : les événements en échec définitif, ou qui ont épuisé leurs nouvelles tentatives, ne sont pas renvoyés. Si l'endpoint a répondu 410 Gone, le callback a désormais le statut En échec et doit être remplacé.
  • L'URL est refusée quand vous enregistrez : l'endpoint doit commencer par https:// et se résoudre en adresse publique.

Étapes suivantes

Sur cette page