Aller au contenu principal
pipelinebrut.fr — CI/CD · automatisation · terrain
Automatisation

Webhooks fiables : arrêter les doublons et les événements perdus dans vos automatisations

Construisez des webhooks robustes : signatures, idempotence, retries et files d’attente pour éviter doublons et événements perdus.

Par Julien Mercier 8 min de lecture

Traitez un webhook comme une livraison asynchrone faillible : vérifiez la requête, conservez-la durablement, répondez vite, puis exécutez ses effets métier de façon idempotente. Un même événement peut arriver plusieurs fois, en retard ou ne jamais parvenir à destination.

Réception et déduplication

Un webhook n’est pas une transaction distribuée. L’émetteur attend une réponse pendant un délai limité et peut renvoyer l’événement après un timeout, sans savoir si votre application avait déjà commencé son traitement.

L’endpoint doit donc vérifier l’origine de la requête, stocker l’événement et confier le travail à un mécanisme asynchrone. Répondez avec un code 2xx seulement après confirmation de cette écriture durable.

  • Vérifiez l’authenticité avec le mécanisme de l’émetteur. Stripe demande de vérifier la signature de chaque webhook, et GitHub recommande aussi de valider la signature de charge utile avec le secret du webhook avant traitement : consultez la documentation GitHub sur la validation des livraisons.
  • Conservez le corps HTTP brut avant toute transformation lorsque la signature porte sur les octets reçus : re-sérialiser un JSON parsé peut invalider la vérification.
  • Validez le minimum utile — type d’événement, identifiant, format et taille attendue — et refusez les requêtes non authentifiées sans révéler le secret de validation.
  • Enregistrez l’événement dans une table d’ingestion ou une file avec sa source, son identifiant externe, son type, sa date de réception, le payload brut ou sa référence, son statut et les erreurs éventuelles.

Utilisez l’identifiant d’événement fourni par la source et imposez une contrainte d’unicité, par exemple sur source + event_id. Si cet enregistrement existe déjà, reconnaissez le doublon sans relancer l’effet métier.

La déduplication doit aussi couvrir le service appelé. Lorsque c’est possible, transmettez-lui une clé d’idempotence ; par exemple, l’API Stripe prend en charge des clés d’idempotence pour les requêtes POST.

Évitez de marquer un événement comme terminé avant l’appel externe, ce qui pourrait perdre l’action en cas de panne. Inversement, appeler ce service sans trace locale peut produire un doublon au redémarrage ; conservez donc un état de traitement permettant la reprise.

Reprise et contrôle

Réessayez les erreurs transitoires, comme les timeouts, limitations temporaires ou indisponibilités, avec un délai croissant et du jitter. Pour un payload invalide, un type non supporté ou une ressource définitivement absente, arrêtez les retries automatiques et conservez la cause.

Après un nombre limité de tentatives ou pour une erreur inconnue, placez le message dans une dead-letter queue (DLQ). Elle doit conserver le payload, les tentatives, l’erreur et la version du code, afin de permettre une alerte, une correction et un rejeu contrôlé.

Ajoutez une réconciliation lorsque l’outil source le permet : comparez régulièrement les événements ou objets attendus avec ceux intégrés, à l’aide d’un curseur ou d’un horodatage conservé. Mesurez au minimum le volume reçu, les événements dédupliqués et les messages en échec ou en DLQ ; évitez aussi de journaliser des secrets ou des données personnelles sans politique de rétention claire.