Récepteur de webhooks fiable : signature, idempotence, file et relances

Prompt

Agis comme un ingénieur backend expérimenté en intégrations et systèmes distribués.

Je dois recevoir des webhooks de façon fiable :
- Fournisseur et méthode de signature : {{fournisseur}}
- Événements utiles et traitement de chacun : {{evenements}}
- Stack : {{stack}}
- Système de files disponible : {{file}}

Livrables :
1. Un schéma textuel du flux : réception, vérification, persistance, mise en file, traitement, relances et file des messages en échec.
2. L’endpoint de réception :
   - Lit le corps brut avant tout parsing et vérifie la signature HMAC avec une comparaison à temps constant.
   - Rejette les requêtes dont l’horodatage sort d’une courte fenêtre, pour éviter le rejeu.
   - Enregistre l’événement et répond 2xx en quelques millisecondes ; aucune logique lourde dans la requête.
3. L’idempotence : table des événements avec l’identifiant du fournisseur en clé unique, états (reçu, en cours, traité, en échec) et conduite à tenir si le même événement arrive deux fois.
4. Le worker : traitement avec backoff exponentiel et jitter, nombre maximal de tentatives, distinction entre erreurs transitoires et définitives, file des messages en échec et moyen de les rejouer.
5. L’ordre d’arrivée : gérer les événements désordonnés (par exemple vérifier la version ou la date de la ressource, ou la relire via l’API du fournisseur).
6. Journalisation et alertes : quoi journaliser sans stocker de données sensibles et quelles métriques suivre.
7. Les tests : signature valide et invalide, événement en double, horodatage ancien, échec transitoire résolu et échec définitif envoyé dans la file d’échec.
8. Comment tester en local (tunnel ou transfert d’événements) sans exposer le secret.

Contraintes :
- Ne devine pas le format exact de signature ni les noms d’en-têtes : si je ne les donne pas, indique [À COMPLÉTER] et dis-moi où les trouver dans la documentation du fournisseur.
- Le secret est lu depuis des variables d’environnement ou un gestionnaire de secrets, jamais dans le code.
- S’il manque une information clé, demande-la avant d’écrire le code.

Comment l'utiliser

Exemple d'utilisation

Exemple de résultat

Passerelle → POST /webhooks/paiements → vérifier signature + horodatage → INSERT événement (unique)
           → commit → 200 → Celery : traiter → retries avec backoff → dead-letter

@router.post("/webhooks/paiements")
async def recevoir(request: Request, db: AsyncSession = Depends(get_db)) -> dict:
    brut = await request.body()                       # corps brut, avant tout parsing
    ts = request.headers.get("[À COMPLÉTER : en-tête horodatage]", "")
    signature = request.headers.get("[À COMPLÉTER : en-tête signature]", "")
    if not ts.isdigit() or abs(time.time() - int(ts)) > 300:
        raise HTTPException(400, "horodatage absent ou expiré")

    # Format du message signé selon la doc du fournisseur : [À COMPLÉTER]
    attendue = hmac.new(settings.webhook_secret.encode(),
                        f"{ts}.".encode() + brut, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(attendue, signature):  # comparaison à temps constant
        raise HTTPException(400, "signature invalide")

    evenement = json.loads(brut)
    stmt = (insert(WebhookEvent)
            .values(provider_event_id=evenement["id"], type=evenement["type"],
                    payload=evenement, statut="recu")
            .on_conflict_do_nothing(index_elements=["provider_event_id"])
            .returning(WebhookEvent.id))
    nouvel_id = (await db.execute(stmt)).scalar_one_or_none()
    await db.commit()
    if nouvel_id is not None:                         # doublon → pas de nouvel envoi en file
        traiter_evenement.delay(nouvel_id)
    return {"ok": True}

Informations clés

Catégorie

Programmation et développement · API

Type de résultat

Code

Niveau

Avancé

Conçu pour

ChatGPT, Claude, Gemini et Microsoft Copilot

Vérifié sur

En attente de vérification éditoriale

Variables

Fournisseur et signature, Événements et actions, Stack et Système de files

Langue

Français

Prix

Gratuit, sans inscription

Mis à jour

07/11/2026

Questions fréquentes