Documentation — Webhooks

Modèle de données

Un webhook associe un événement déclencheur à une URL de destination (HTTPS obligatoire) et à un secret de signature. Le statut permet de suspendre sans supprimer ; le taux de succès et le dernier envoi sont recalculés à chaque livraison.

{
  "evenement": "commande.creee",   // commande.creee | commande.expediee | stock.seuil_atteint | facture.payee | client.cree
  "url": "https://hooks.slack.com/services/T024/B11/xxx",
  "statut": "active",              // active | error | paused
  "secret": "whsec_8fK2mQ9pL4xT7vB1",
  "tauxSucces": 99,
  "dernierEnvoi": "2026-06-12T09:41:23Z"
}

Signature HMAC

Chaque livraison est signée avec le secret du webhook (whsec_…) : l'en-tête X-Webhook-Signature contient le HMAC-SHA256 de timestamp.corps_json. Le destinataire recalcule la signature et rejette toute requête dont l'horodatage a plus de 5 minutes (protection anti-rejeu).

import hashlib
import hmac

def verifier_signature(secret: str, timestamp: str, corps: bytes, signature: str) -> bool:
    message = f"{timestamp}.".encode() + corps
    attendu = hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
    return hmac.compare_digest(attendu, signature)

Politique de retries

• Succès — toute réponse 2xx en moins de 10 secondes ; la livraison est journalisée (code, durée).
• Échec — réponse 4xx/5xx ou timeout : nouvelle tentative avec backoff exponentiel (1 min, 5 min, 30 min, 2 h, 12 h).
• Statut « Erreur » — après 5 échecs consécutifs, le webhook passe en erreur et une alerte est émise ; les tentatives continuent.
• Suspension automatique — après 72 h d'échecs ininterrompus, le webhook est mis en pause pour protéger le destinataire.

Intégration en production

Le simulateur fonctionne en local (état React seedé). Pour brancher un vrai backend : persister les webhooks (table webhooks) et les livraisons (table webhook_deliveries, l'équivalent du « Journal des livraisons »), publier les événements métier sur un bus interne, puis déléguer l'envoi HTTP à un worker qui signe chaque requête, applique les retries et met à jour le taux de succès. La rotation du secret se fait sans coupure : deux secrets actifs pendant la fenêtre de migration.

Ouvrir le simulateur