Configurer les webhooks
Déclarez un callback dans Studio, abonnez-le à des événements, authentifiez-le et vérifiez chaque livraison.
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
httpsimple 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 :
-
Sélectionnez l'onglet Webhooks.

-
Sélectionnez Nouveau webhook.

-
Saisissez le Nom, ici
Lindenhall CRM.
Un callback par système en aval permet d'isoler les pannes.
-
Saisissez l'URL du endpoint, ici
https://crm.lindenhall.example/omnilab/events.
-
Laissez le champ Méthode HTTP sur
POST, sauf si le système récepteur attend une autre méthode.
-
Sélectionnez Créer.

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

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 :
-
Sur la ligne du callback, sélectionnez Abonnements.

-
Sélectionnez Ajouter un abonnement.

-
Saisissez un Nom pour cette partie du trafic, ici
CRM sync — reward wins only.
-
Dans le champ Types d'événements, sélectionnez les événements voulus, ici Gagné et Échangé(s).

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.
-
(Facultatif) Dans le champ Type d'événement personnalisé, saisissez un type que le sélecteur ne liste pas, ici
submission.created.v1.
-
(Facultatif) Sélectionnez Ajouter un élément personnalisé.

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.
-
(Facultatif) Pour limiter la livraison à une organisation, sélectionnez Ajouter un filtre.

-
(Facultatif) Dans la nouvelle ligne de filtre, remplacez la clé
tenant_idpargroup_id.
-
(Facultatif) Saisissez l'ID de l'organisation comme valeur, ici
groups/6946c01f-8542-471c-9e2f-dac2661027c6.
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.
-
Sélectionnez Créer.

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 :
npm init -y
npm pkg set type=module
npm install expressimport 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 :
OMNILAB_SIGNING_SECRET='<your signing secret>' node server.jsLe 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 :
| Mode | Adapté à | Ce que vous saisissez |
|---|---|---|
| Aucun | L'endpoint s'appuie uniquement sur la vérification de signature | Rien |
| Basique | Les endpoints qui attendent un nom d'utilisateur et un mot de passe | Nom d'utilisateur, puis Mot de passe sous Identifiants secrets |
| Jeton Bearer | Les services qui acceptent un jeton d'API statique | Nom 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ée | ID 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 :
-
Sur la ligne du callback, ici Analytics export, sélectionnez Modifier.

-
Sélectionnez l'onglet Authentification.

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

-
Saisissez l'ID client, ici
lindenhall-analytics.
-
Saisissez l'Endpoint du jeton, ici
https://idp.lindenhall.example/oauth2/token.
-
Saisissez les Portées, ici
analytics.write.
-
Saisissez la Méthode d'authentification du client, ici
client_secret_post.
-
Sélectionnez Enregistrer l'authentification.

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

-
Sélectionnez Enregistrer les secrets.

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 :
-
Sur la ligne du callback, sélectionnez Modifier.

-
Sélectionnez l'onglet Secrets.

-
Sélectionnez Renouveler le secret de signature.

-
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.
-
Copiez le secret de la fenêtre Nouveau secret de signature dans votre stockage de secrets.

-
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 :
{
"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_idne 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_idouinteraction_id. Le champ de clé suggère aussicontact_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
À propos des webhooks
Comment fonctionnent les callbacks, les abonnements, les signatures et les nouvelles tentatives quand la plateforme envoie des événements à votre endpoint.
Référence des événements
Chaque type d'événement, les webhooks et les functions qui le reçoivent, et les champs de ses données.