Configurer les webhooks

Enregistrer un callback dans Studio, l'abonner à des événements, l'authentifier et vérifier la signature de chaque livraison.

Mettez en place un endpoint qui reçoit les événements OmniLab au moment où ils se produisent, pour que votre CRM, vos analytics ou votre système de logistique réagissent sans interrogation périodique. Vous réalisez toute la configuration vous-même dans Enterprise Settings → Webhooks.

Prérequis

Un endpoint HTTPS public capable de recevoir les requêtes d'OmniLab. Le http simple est refusé.
Un emplacement sécurisé de votre côté pour stocker le secret de signature, affiché une seule fois à la création.
Des endpoints distincts pour la préproduction et la production, afin que le trafic de test n'atteigne jamais vos systèmes réels.

Créer le callback

Ouvrez le panneau Webhooks

Allez dans Enterprise Settings, puis dans l'onglet Webhooks. Il liste tous les callbacks enregistrés pour le groupe dans lequel vous travaillez, avec leur statut et leur endpoint.

Panneau Webhooks des Enterprise Settings listant trois callbacks avec leurs badges de statut

Enregistrez l'endpoint

Sélectionnez New webhook et renseignez trois champs :

Champ	Ce que vous saisissez
Name	Un libellé que vous reconnaîtrez plus tard, par exemple `CRM sync`. Un callback par responsabilité aval permet d'isoler les pannes.
Endpoint URL	L'adresse à laquelle OmniLab envoie les événements. Elle doit commencer par `https://`.
HTTP method	`POST`, sauf si le système récepteur exige autre chose.

Sélectionnez Create.

Boîte de dialogue Create webhook avec le nom, l'URL d'endpoint et la méthode HTTP renseignés

Copiez le secret de signature

La création affiche le secret de signature une seule fois. Copiez-le directement dans votre coffre à secrets avant de fermer la boîte de dialogue : OmniLab ne peut plus l'afficher ensuite, et le seul moyen d'obtenir un secret exploitable est d'en générer un nouveau.

Boîte de dialogue du secret de signature avertissant que la valeur n'est affichée qu'une fois, avec un bouton de copie

C'est le seul moment où le secret est visible

Si vous fermez la fenêtre sans copier, ouvrez l'onglet Secrets du callback et sélectionnez Rotate signing secret pour en émettre un nouveau. La rotation prend effet immédiatement : tout vérificateur utilisant encore l'ancien secret se met à rejeter les livraisons.

Abonner le callback à des événements

Un nouveau callback ne reçoit rien tant qu'il n'a pas au moins un abonnement. Ouvrez son onglet Subscriptions et sélectionnez Add subscription.

Nommez l'abonnement

Choisissez un nom qui décrit la portion de trafic concernée, par exemple CRM sync — gains uniquement. Plusieurs abonnements peuvent pointer vers le même callback.

Choisissez les types d'événements

Ouvrez Select event types… et cochez les événements souhaités. Ils sont regroupés par famille — Touchpoint, Reward, Booking, etc. — et se recherchent par nom. Les événements sélectionnés apparaissent sous forme de puces supprimables sous le sélecteur.

Si l'événement dont vous avez besoin n'est pas dans la liste, saisissez son nom exact dans le champ Custom event type et sélectionnez Add custom. Les entrées personnalisées s'affichent avec un contour en pointillés.

Une sélection vide abonne à tout

Laisser la liste d'événements vide ne signifie pas « aucun événement » : le callback reçoit alors tous les événements émis par la plateforme. Sélectionnez au moins un type d'événement, sauf si vous voulez réellement le flux complet.

Sélecteur de types d'événements filtré sur les événements reward, deux d'entre eux cochés et affichés en puces

Restreignez la livraison avec des filtres

Les filtres sont facultatifs. Sans eux, tous les événements des types sélectionnés sont livrés au callback. Ajoutez-en un avec Add filter, puis choisissez une clé et saisissez une valeur.

Clé de filtre	À utiliser quand
`tenant_id`	Le callback doit recevoir tout le flux du tenant
`group_id`	Le flux doit être restreint à une organisation ou un groupe
`interaction_id`	Le callback ne doit voir qu'une seule campagne ou expérience

Les filtres se combinent avec un ET logique et correspondent à l'identique : deux filtres doivent donc être satisfaits tous les deux pour qu'un événement soit livré.

Formulaire d'abonnement montrant le nom, les puces d'événements sélectionnés, un filtre interaction_id et le statut

Seules ces trois clés sont acceptées

Le champ de clé suggère également contact_id, mais l'enregistrement d'un abonnement qui l'utilise échoue à la validation. Tenez-vous-en à tenant_id, group_id et interaction_id.

Enregistrez et vérifiez le statut

Sélectionnez Create. L'abonnement apparaît dans la liste avec le statut Active, accompagné de ses types d'événements et de ses filtres. Utilisez Pause pour interrompre la livraison tout en conservant la configuration, et Resume pour la réactiver.

Onglet Subscriptions montrant un abonnement actif avec ses types d'événements et son filtre

S'authentifier auprès de votre endpoint

Si votre récepteur exige ses propres identifiants, ouvrez l'onglet Authentication et choisissez un mode.

Mode	Cas d'usage	Ce que vous saisissez
None	L'endpoint est protégé autrement et s'appuie uniquement sur la vérification de signature	Rien
Basic	Endpoints historiques attendant un identifiant et un mot de passe	Username, Password
Bearer token	Services acceptant un jeton d'API statique	Bearer token, et éventuellement un Custom header name — laissez-le vide pour utiliser l'en-tête `Authorization` standard
OAuth2 (client credentials)	Plateformes qui émettent des jetons de courte durée	Client ID, Token endpoint, Scopes, Client auth method, Audience facultatif, et Client secret

L'onglet enregistre en deux temps. Save authentication stocke les réglages ; Save secrets stocke le mot de passe, le jeton ou le secret client. Les secrets sont en écriture seule : ils ne sont plus jamais affichés après enregistrement, et laisser un champ vide conserve la valeur stockée au lieu de l'effacer.

Onglet Authentication avec le mode OAuth2 client credentials sélectionné et ses champs renseignés

Remodeler la requête (facultatif)

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

HTTP method et Content type de la requête sortante.
URL template — remplace l'endpoint défini dans l'onglet General. Pratique pour router des types d'événements vers des chemins différents.
Body template — laissez vide pour envoyer le JSON brut de l'événement.
Custom headers — envoyés à chaque livraison.

Les templates référencent les champs de l'événement avec {{event.<field>}} :

Body template

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

Les en-têtes de signature d'OmniLab — webhook-id, webhook-timestamp et webhook-signature — ne peuvent pas être remplacés par un en-tête personnalisé.

Vérifier les livraisons de votre côté

Chaque livraison porte une signature HMAC-SHA256 dans l'en-tête webhook-signature, calculée avec votre secret de signature sur le corps brut de la requête.

Vérifiez la signature sur le corps brut, avant de le parser ou d'effectuer le moindre traitement.
Stockez le webhook-id et ignorez les doublons, pour qu'un nouvel essai n'applique jamais deux fois la même modification.
Répondez 2xx dès que vous avez accepté la requête, et déportez les traitements lents vers votre propre file.

Comment votre réponse est interprétée :

Votre réponse	Ce que fait OmniLab
`2xx`	Considère la livraison comme réussie
`429` ou tout `5xx`	Réessaie la livraison
Tout autre `4xx`	Considère l'échec comme définitif et ne réessaie pas

Cette dernière ligne compte : renvoyer 400 parce que votre parseur a échoué fait perdre l'événement. Renvoyez un 5xx quand vous voulez que la livraison revienne.

Suivre la santé des livraisons

Chaque carte de callback porte un badge de statut :

Verified — l'état normal. Un callback est créé Verified et le reste tant qu'il accepte les livraisons : ce n'est donc pas la preuve que du trafic a été testé.
Failing — votre endpoint a répondu 410 Gone. Dépliez la carte, ou ouvrez l'onglet General, pour lire le motif enregistré par OmniLab.

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

410 Gone est la façon dont un récepteur annonce « cet endpoint est retiré ». OmniLab le prend au mot : le callback est désactivé, cesse de recevoir des événements, et rien dans le panneau ne le réactive. Ne renvoyez 410 que si c'est bien votre intention — et si cela arrive par accident, créez un callback de remplacement et recréez ses abonnements.

L'onglet Secrets affiche également une référence de secret. C'est un identifiant du secret stocké, utile pour les échanges avec le support, et non le secret lui-même : il ne permet ni de signer ni de vérifier quoi que ce soit.

En cas de blocage

Le callback ne reçoit rien — vérifiez qu'il a au moins un abonnement, que celui-ci est Active et non Paused, et qu'un éventuel nom d'événement personnalisé correspond exactement à l'événement de la plateforme. Un nom non reconnu est enregistré sans avertissement, puis ne correspond jamais à rien.
Un abonnement refuse de s'enregistrer — chaque filtre exige une clé et une valeur, et la clé doit faire partie des trois clés supportées.
Les vérifications de signature échouent soudainement — le secret de signature a été renouvelé. Mettez à jour votre vérificateur avec le secret affiché lors de la rotation.
Les livraisons se sont arrêtées après un incident — un 4xx autre que 429 est considéré comme définitif, donc ces événements n'ont pas été réessayés. Si le récepteur a répondu 410 Gone, le callback lui-même est désormais Failing et doit être remplacé. Sinon, corrigez le récepteur, puis faites rejouer les données manquantes par le système amont si nécessaire.
L'URL est refusée à l'enregistrement — les endpoints doivent commencer par https://.

Pour aller plus loin

WebhooksÀ propos des webhooksPasser en revue signatures, retries et comportement des callbacks avant l'implémentation.WebhooksRéférence des événements webhookVoir ce que signifie chaque événement et quand il se déclenche.Comptes clientsPatterns d'intégration courantsAppliquer les webhooks au CRM, aux analytics et aux parcours participants.

Configurer les webhooks

Sur cette page