Configurer les webhooks
Préparer le callback, les règles d'abonnement, l'authentification et la vérification de signature nécessaires à une intégration webhook OmniLab.
Préparez une implémentation de webhook avec OmniLab. Les enregistrements de callback et d'abonnement sont configurés avec les équipes OmniLab, mais vous pouvez préparer à l'avance votre endpoint, l'authentification, les filtres et la logique de vérification.
Prérequis
- Un endpoint HTTPS public capable de recevoir les requêtes OmniLab
- Un stockage de secrets côté serveur pour les secrets de signature et les identifiants de callback
- Des receivers staging et production séparés
- Une liste claire des types d'événements et des filtres dont vous avez besoin
Préparer la mise en place
Décidez de la responsabilité de chaque callback
Préférez un callback par responsabilité aval. Par exemple, utilisez un callback pour la synchro CRM et un autre pour l'export analytics, plutôt que d'envoyer tous les événements à un seul gros receiver.
Choisissez le modèle d'authentification
Choisissez le modèle le plus simple que votre service aval accepte :
| Mode d'auth | Bon usage |
|---|---|
| None | Le receiver est déjà protégé autrement et n'a besoin que de la vérification de signature |
| Basic | Endpoints anciens qui utilisent déjà un nom d'utilisateur et un mot de passe |
| Bearer | Services aval qui attendent un token API statique |
| OAuth 2.0 client credentials | Plateformes qui émettent des access tokens à courte durée de vie |
Définissez les abonnements
Chaque abonnement lie un callback à un ou plusieurs types d'événements, puis restreint la livraison avec des filtres optionnels.
{
"subscription_name": "Reward wins for summer campaign",
"callback": "reward-win-receiver",
"event_category_types": ["reward.won.v1", "reward.redeemed.v1"],
"filters": [
"tenant_id=<tenant-id>",
"interaction_id=<interaction-id>"
]
}Utilisez tenant_id lorsque le receiver doit voir tout le flux du tenant, group_id lorsque le flux doit être restreint à une organisation ou un groupe, et interaction_id lorsque vous avez besoin d'un flux propre à une campagne.
Implémentez la vérification de signature et l'idempotence
Vérifiez le header webhook-signature contre le body brut avant tout traitement. Stockez ensuite le webhook-id pour que les retries ou les livraisons en double ne répètent pas les effets de bord aval.
Testez les retries et la rotation de secret en staging
Avant le go-live, simulez des réponses de succès, 429, 5xx et 410 Gone. Faites tourner le secret de signature et confirmez que votre vérificateur accepte la signature courante et la précédente pendant la fenêtre de transition.
Transformation de requête optionnelle
OmniLab peut éventuellement transformer les requêtes de callback en modifiant :
- la méthode HTTP
- le content type
- le body de la requête
- l'URL de destination
- les headers personnalisés
Ces transformations sont rendues avec Liquid et peuvent référencer l'objet event sortant.
{
"eventId": "{{ event.id }}",
"eventType": "{{ event.type }}",
"rewardId": "{{ event.payload.reward_id }}"
}OmniLab réserve ses propres headers de signature et d'auth ; les headers personnalisés ne doivent donc servir qu'à vos besoins aval.
Checklist du receiver
- Renvoyez vite une réponse
2xxune fois la requête acceptée. - Déplacez le travail aval lourd sur une file ou un worker asynchrone.
- Journalisez
webhook-id, le type d'événement et le code de statut pour le debug. - Gardez séparés les URLs de callback, identifiants et secrets de staging et de production.
- Rendez le receiver idempotent avant le démarrage du trafic en production.
Pour aller plus loin
À propos des webhooks
Revoir les signatures, les retries et le comportement des callbacks avant l'implémentation.
Référence des événements webhook
Choisir les noms d'événements et les filtres à mettre dans chaque abonnement.
Patterns d'intégration courants
Appliquer les webhooks aux parcours CRM, analytics et participant.