Webhooks expliqués : payloads signés et retries

Pourquoi les Webhooks sont à la fois puissants et fragiles

Les webhooks alimentent les intégrations en temps réel : notifications de paiement, déclencheurs CI/CD, messages de chat. Mais ils présentent deux défis majeurs : la sécurité (comment savoir que la requête provient de l'expéditeur attendu ?) et la fiabilité (que se passe-t-il si le récepteur est indisponible ?). Cet article vous montre comment répondre à ces deux problématiques avec des payloads signés et des stratégies de retry.

Qu'est-ce qu'un Webhook ?

Un webhook est une requête HTTP POST envoyée par un fournisseur à un consommateur lorsqu'un événement se produit. Contrairement au polling, les webhooks poussent les données en quasi temps réel, réduisant la latence et la charge serveur. Le fournisseur doit garantir l'authenticité de la requête ; le consommateur doit la traiter de manière fiable.

Sécuriser les Webhooks avec des Payloads Signés

Un payload signé utilise une clé secrète pour créer une signature cryptographique (généralement HMAC-SHA256) du corps de la requête. Le récepteur recalcule la signature et la compare à celle présente dans l'en-tête. Si elles correspondent, le payload est authentique et non altéré.

Comment générer et vérifier les signatures

Voici un flux typique :

1. Le fournisseur et le consommateur partagent une clé secrète (par exemple via un dashboard).
2. Le fournisseur calcule HMAC-SHA256(secret, payload) et l'envoie dans un en-tête comme X-Signature.
3. Le consommateur lit le corps brut, calcule le même HMAC et compare à l'aide d'une fonction à temps constant.

Exemple en Node.js :

const crypto = require('crypto');

function verifySignature(secret, payload, signature) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(payload);
  const digest = hmac.digest('hex');
  return crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(signature));
}

Utilisez toujours une comparaison à temps constant pour prévenir les attaques temporelles. Ne parsez jamais le corps avant la vérification—utilisez un middleware de corps brut.

Implémenter des Retries pour une Livraison Fiable

Même avec des signatures, des défaillances réseau ou des pannes temporaires peuvent entraîner l'échec de la livraison d'un webhook. Un mécanisme de retry robuste garantit une livraison éventuelle.

Stratégies de Retry

• Backoff exponentiel : Attendez plus longtemps entre chaque tentative (par exemple 1s, 2s, 4s, 8s).
• Nombre maximum de tentatives : Limitez les retries (par exemple 5 tentatives) pour éviter les boucles infinies.
• File de lettres mortes : Après le nombre maximum de tentatives, stockez l'événement pour inspection manuelle.
• Idempotence : Incluez un ID d'événement unique pour que le consommateur puisse ignorer les doublons.

Exemple de logique de retry en Python :

import time
import requests

def send_webhook(url, payload, max_retries=5):
    for attempt in range(max_retries):
        try:
            response = requests.post(url, json=payload, timeout=5)
            if response.status_code == 200:
                return True
        except requests.RequestException:
            pass
        time.sleep(2 ** attempt)  # exponential backoff
    return False

Bonnes Pratiques pour les Consommateurs de Webhooks

• Répondez rapidement avec un code 2xx ; traitez de manière asynchrone si nécessaire.
• Validez la signature avant tout traitement.
• Utilisez des clés d'idempotence pour gérer les livraisons en double.
• Journalisez tous les webhooks entrants pour le débogage.
• Surveillez les échecs et alertez en cas d'erreurs répétées.

Comparaison : Polling vs Webhooks

FAQ

Qu'est-ce qu'un payload de webhook signé ?

Un payload signé inclut une signature cryptographique (par exemple HMAC) qui permet au récepteur de vérifier que la requête provient d'une source de confiance et n'a pas été altérée.

Combien de fois dois-je réessayer un webhook échoué ?

Il n'existe pas de nombre universel, mais 3 à 5 tentatives avec un backoff exponentiel est courant. Au-delà, journalisez l'événement pour examen manuel.

Puis-je utiliser JWT au lieu de HMAC pour les signatures de webhook ?

Oui, certains fournisseurs utilisent JWT. Le principe est le même : vérifiez la signature et les claims du token avant de faire confiance au payload.

Besoin d'inspecter des payloads ou des logs de webhook ? Essayez notre JSON Formatter pour formater et valider rapidement des payloads JSON.