À propos des webhooks

Un webhook OmniLab associe deux éléments :

• un callback, c'est-à-dire la destination HTTP et ses règles de sécurité
• un abonnement, c'est-à-dire les événements que vous voulez recevoir sur ce callback

En pratique, plusieurs abonnements peuvent pointer vers un même callback si vous voulez centraliser le traitement sur un receiver unique.

Comment fonctionne la livraison

Le callback définit notamment :

• l'URL cible
• la méthode HTTP, généralement POST
• le content type, généralement application/json
• le mode d'authentification sortant éventuel
• le secret de signature utilisé pour signer la charge utile
• les transformations éventuelles du body, de l'URL, ou de certains headers

L'abonnement définit notamment :

• le ou les event_type à écouter
• les filtres de périmètre, par exemple tenant_id, group_id, ou interaction_id
• l'activation ou non de la livraison pour ce flux

Headers de livraison à connaître

Lorsqu'une signature est activée, votre receiver voit généralement :

• webhook-id
• webhook-timestamp
• webhook-signature
• User-Agent

Le header webhook-signature contient une signature HMAC-SHA256 encodée en base64, sous une forme de type v1,<signature>.

Principe de vérification de signature

OmniLab signe le contenu suivant :

webhook-id + "." + webhook-timestamp + "." + raw_request_body

Votre receiver doit :

1. conserver le body brut exact de la requête
2. reconstruire la chaîne signée dans le même ordre
3. recalculer le HMAC-SHA256 avec le secret partagé
4. comparer le résultat avec la valeur du header webhook-signature
5. rejeter les messages trop anciens selon votre fenêtre de tolérance au replay

Exemple d'usage

• un CRM écoute reward.won.v1 pour enrichir la fiche contact
• un data pipeline écoute touchpoint.completed.v1 et booking.created.v1
• un portail participant écoute booking.cancelled.v1 pour synchroniser son affichage

Résultats de livraison importants

• une réponse 2xx confirme que la livraison est acceptée
• une réponse 429 peut être retentée, et Retry-After est respecté lorsqu'il est fourni
• les erreurs réseau, timeouts, et 5xx déclenchent aussi des retries
• une réponse 410 Gone désactive le callback, utile si un endpoint doit être retiré proprement

Pour aller plus loin