Webhooks auto-correctifs : Utiliser des LLM locaux pour réessayer et réparer automatiquement les payloads API échoués au bord du tunnel

Webhooks maintiennent la synchronisation des systèmes modernes, des événements de paiement et notifications de dépôt de code aux bus d’événements internes. Ils échouent aussi de façons qui sont fastidieuses à déboguer. En développement local, l’échec n’est généralement pas dû au réseau. Votre gestionnaire rejette un payload parce qu’un champ a le mauvais type, une propriété requise est absente, ou la version de l’API du fournisseur ne correspond plus à ce que votre code attend.

Cet article décrit un pattern en développement : un petit proxy placé entre votre tunnel et votre application, qui intercepte les échecs de validation (400/422), demande à un modèle local de réparer le payload, et réessaie une fois. Il couvre ce que cela peut et ne peut pas corriger, comment cela interagit avec les signatures de webhook, et où ce n’est pas l’outil adapté. Les faits concernant les fournisseurs et outils ont été vérifiés contre leur documentation en octobre 2026. Ils évoluent, donc vérifiez à nouveau avant de vous y fier.

---

1. Pourquoi les webhooks échouent en développement local

Modes d’échec courants

1. Dérive de version API. Stripe fixe la version du payload webhook à une version spécifique. Selon la documentation de versioning de Stripe, les événements utilisent la version définie lors de la création du point de terminaison webhook, ou la valeur par défaut du compte si aucune n’est spécifiée. Les versions Stripe sont datées et portent maintenant des noms de release, par exemple 2024-12-18.acacia, 2025-08-27.basil, et 2026-09-30.endive. Les releases mensuelles dans une version nommée sont rétrocompatibles, mais une nouvelle version majeure peut inclure des changements incompatibles. Un échec local courant est un décalage : votre SDK fixe une version, alors que le point de terminaison, et donc le payload, en utilisent une autre.
2. Incompatibilités de types. Un ID ou un montant arrive sous forme de chaîne alors que votre validateur attend un entier, ou inversement.
3. Champs manquants ou renommés. Un champ requis est absent, ou une clé dépréciée a été remplacée.
4. Corps mal formés. Rare en pratique, mais un JSON tronqué ou mal échappé échouera lors de l’analyse avant toute vérification de schéma.
5. Strictness local. Votre gestionnaire de développement peut valider de façon plus stricte que ce à quoi les payloads d’échantillon du fournisseur ont été écrits.

Ce que font les fournisseurs quand votre endpoint rejette un événement

Fournisseur	Réessais automatiques	Récupération manuelle
Stripe	En mode live, jusqu’à 3 jours avec backoff exponentiel. En sandbox, trois tentatives sur quelques heures. Stripe réessaie sur des réponses non-2xx.	stripe events resend <event_id> --webhook-endpoint=<endpoint_id> fonctionne pour des événements jusqu’à 30 jours.
GitHub	Aucun. GitHub ne redélivre pas automatiquement les livraisons échouées.	Redélivrer depuis la liste “Livraisons récentes” ou via l’API REST, pour les livraisons des 3 derniers jours.

Deux détails importants pour ce design. D’abord, réessayer un événement dont le payload est incompatible avec votre gestionnaire produira la même rejection à chaque fois, donc un 422 dû à un décalage de schéma ne se corrigera pas tout seul. Ensuite, il n’existe pas de “dead-letter queue” universelle chez le fournisseur. Une DLQ, c’est quelque chose que vous construisez ou obtenez via une passerelle de webhook. GitHub, par exemple, enregistre simplement l’échec.

Le timing compte aussi. GitHub attend une réponse 2xx dans les 10 secondes et considère une réponse plus lente comme un échec. Stripe vous dit de répondre rapidement en 2xx. Toute approche ajoutant un appel au modèle dans le chemin de la requête doit respecter ces limites.

Essayez d’abord les outils plus simples

Avant d’ajouter un modèle, considérez ce qui existe déjà :

• Rejeu. L’Inspecteur de trafic d’ngrok vous permet de rejouer une requête capturée au lieu d’attendre le réessai du fournisseur. La CLI de Hookdeck relaie les événements vers localhost, met en file d’attente les événements échoués, et vous permet de les réessayer depuis son tableau de bord ou son interface terminale. La CLI de Stripe peut relayer des événements vers un endpoint local avec stripe listen --forward-to localhost:4242/webhook, sans tunnel.
• Transformations. Les transformations de Hookdeck modifient la structure du payload et les en-têtes en transit. C’est la version déterministe de ce que cet article construit.
• Correction du gestionnaire. Si le payload du fournisseur est correct et que votre code est en faute, la bonne correction est dans votre code.

Une correction par LLM est utile dans un cas plus restreint. Vous souhaitez continuer à tester un flux avec un payload que vous ne pouvez pas facilement régénérer, et vous voulez une différence loguée montrant précisément comment le payload et votre schéma sont en désaccord.

---

2. Architecture : un proxy auto-correctif entre le tunnel et votre app

Un tunnel transporte le trafic d’une URL publique vers votre machine. Ni ngrok ni cloudflared ne sont conçus pour appeler un modèle de langage pour vous. La politique de trafic d’ngrok est organisée autour de règles et actions telles que verify-webhook, et cloudflared est un tunnel à usage général. Donc, l’étape de réparation appartient à un petit proxy que vous contrôlez, placé entre l’agent du tunnel et votre application :

[ Fournisseur de webhook ]
        │  POST /webhook
        ▼
[ URL publique du tunnel (ngrok / cloudflared / autre) ]
        │
        ▼
[ Proxy auto-correctif  :3001 ] ──(sur 400/422)──► [ Ollama :11434 ]
        │                                        │
        │◄────────── JSON corrigé ───────────────┘
        ▼
[ Votre app  :3000 ]

Vous pointez le tunnel vers le proxy plutôt que vers l’app, par exemple ngrok http 3001 ou cloudflared tunnel --url http://localhost:3001.

Cycle de vie de la requête

1. Le proxy relaie la requête originale, inchangée, à votre app.
2. Si l’app répond 2xx, ou tout autre statut que 400 ou 422, le proxy renvoie cette réponse telle quelle.
3. Sur 400/422 avec un corps JSON, le proxy envoie le payload et le texte d’erreur de l’app à un modèle local.
4. Le proxy vérifie la sortie du modèle avec des garde-fous (section 5). Si la vérification échoue, il rejette la correction et renvoie l’erreur originale.
5. Si la vérification passe, il réessaie une seule fois avec le corps corrigé et renvoie la réponse de ce réessai si cela réussit.
6. Il enregistre la différence, pour que vous puissiez corriger le vrai décalage dans votre code ou schéma.

Cela fonctionne mieux par couches. Si vous utilisez ngrok, son action verify-webhook peut valider la signature du fournisseur au bord, pour plus de 50 fournisseurs, et rejeter les échecs avec un 403 avant qu’ils n’atteignent votre machine. Vérifiez d’abord, puis réparez.

---

3. Choisir et contraindre le modèle local

Runtime et modèles

Ollama fournit une API REST sur http://localhost:11434 par défaut, et se lie à 127.0.0.1 sauf si vous changez OLLAMA_HOST. Gardez-le en boucle locale. Pour cette tâche précise, de petits modèles suffisent. Voici quelques tailles d’après le README d’Ollama pour les options courantes :

Modèle	Paramètres	Taille de téléchargement
Llama 3.2	3B	environ 2.0 GB
Phi-4 Mini	3.8B	environ 2.5 GB
Gemma 3	4B	environ 3.3 GB
Llama 3.1	8B	environ 4.7 GB

Notez que “Llama 3” en version complète a 8B et 70B. Les tailles 1B et 3B correspondent à Llama 3.2. Phi-3 est encore dans la bibliothèque mais remplacé par Phi-4 et Phi-4 Mini, et la bibliothèque ajoute des familles comme Gemma 4 et Qwen 3.5. Lancez ollama list et testez deux ou trois candidats sur vos payloads, car le bon choix dépend de votre matériel.

Contraindre la sortie, puis la valider quand même

Le paramètre format d’Ollama accepte un schéma JSON, ce qui contraint la génération à cette forme. La documentation sur les sorties structurées recommande aussi de passer le schéma dans le prompt pour ancrer le modèle. Elle indique que les sorties structurées ne sont pas supportées sur le service cloud d’Ollama, donc cela s’applique aux exécutions locales. llama.cpp offre la même capacité via un champ json_schema dans la requête ou une grammaire GBNF.

Le décodage contraint garantit que la sortie se parse et correspond au schéma. Cela ne garantit pas que le contenu est correct. Quelques points pratiques :

• format: "json" seul demande uniquement du JSON. Avec de petits modèles, passez un vrai schéma quand vous en avez, et validez le résultat.
• Fixez temperature: 0 et une seed fixe. Cela réduit la variation entre exécutions, mais ne l’élimine pas complètement.
• Un schéma indique au modèle la forme autorisée. Il ne peut pas lui dire ce qui est vrai.

---

4. Un proxy auto-correctif minimal

Le sketch ci-dessous est en Node.js sans dépendances (v20 ou plus récent). C’est une illustration, pas un code prêt pour la prod. Je l’ai testé avec une app fictive et un modèle fictif pour vérifier le flux : correction réussie, ou veto sur correction. Testez-le avec votre vrai modèle Ollama et votre gestionnaire.

// heal-proxy.mjs
import http from "node:http";
import crypto from "node:crypto";

const APP = process.env.APP_URL ?? "http://127.0.0.1:3000";
const OLLAMA = process.env.OLLAMA_URL ?? "http://127.0.0.1:11434";
const MODEL = process.env.HEAL_MODEL ?? "llama3.2";
const DEV_SECRET = process.env.DEV_SIGNING_SECRET ?? "dev-only-secret";
const PORT = Number(process.env.PORT ?? 3001);
const HEALABLE = new Set([400, 422]);
const PROTECTED = [/^id$/i, /_id$/i, /amount/i, /uuid/i]; // peut être re-typé, jamais re-valeur

const SYSTEM = `Vous réparez les payloads JSON de webhook. Vous recevez {"payload": ..., "validation_error": ...}.
Changez uniquement les champs nommés dans validation_error. Ne changez jamais les identifiants, montants ou timestamps.
Répondez avec le payload corrigé complet en JSON, rien d’autre.`;

const readBody = (req) =>
  new Promise((resolve, reject) => {
    const chunks = [];
    req.on("data", (c) => chunks.push(c)).on("end", () => resolve(Buffer.concat(chunks))).on("error", reject);
  });

function forward(path, method, headers, body) {
  const h = { ...headers };
  for (const k of ["host", "content-length", "connection"]) delete h[k];
  return fetch(APP + path, { method, headers: h, body });
}

function leaves(v, path = "", out = {}) {
  if (v && typeof v === "object") for (const [k, x] of Object.entries(v)) leaves(x, path ? `${path}.${k}` : k, out);
  else out[path] = v;
  return out;
}

// Retourne une chaîne de raison si la correction doit être rejetée, sinon null.
function guard(original, patched, errorText) {
  const a = leaves(original), b = leaves(patched);
  const changed = [...new Set([...Object.keys(a), ...Object.keys(b)])].filter((p) => a[p] !== b[p]);
  if (changed.length === 0) return "le modèle a renvoyé un payload inchangé";
  for (const p of changed) {
    const leaf = p.split(".").pop();
    const isProtected = PROTECTED.some((re) => re.test(leaf));
    if (isProtected && !(p in a && p in b && String(a[p]) === String(b[p]))) return `champ protégé touché : ${p}`;
    if (!errorText.includes(leaf)) return `${p} n’est pas mentionné dans l’erreur de validation`;
  }
  return null;
}

async function heal(payload, errorText) {
  const res = await fetch(`${OLLAMA}/api/chat`, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({
      model: MODEL,
      stream: false,
      format: "json",
      options: { temperature: 0, seed: 7 },
      messages: [
        { role: "system", content: SYSTEM },
        { role: "user", content: JSON.stringify({ payload, validation_error: errorText }) },
      ],
    }),
    signal: AbortSignal.timeout(8000),
  });
  const data = await res.json();
  return JSON.parse(data.message.content);
}

http
  .createServer(async (req, res) => {
    const raw = await readBody(req);
    let upstream = await forward(req.url, req.method, req.headers, raw);
    let body = Buffer.from(await upstream.arrayBuffer());

    if (HEALABLE.has(upstream.status) && /json/.test(req.headers["content-type"] ?? "")) {
      try {
        const original = JSON.parse(raw.toString("utf8"));
        const errorText = body.toString("utf8").slice(0, 2000);
        const patched = await heal(original, errorText);
        const veto = guard(original, patched, errorText);
        if (veto) {
          console.warn("[heal] vetoed:", veto);
        } else {
          const patchedRaw = Buffer.from(JSON.stringify(patched));
          const headers = { ...req.headers, "x-auto-patched": "true" };
          for (const k of ["stripe-signature", "x-hub-signature", "x-hub-signature-256"]) delete headers[k];
          headers["x-dev-signature"] =
            "sha256=" + crypto.createHmac("sha256", DEV_SECRET).update(patchedRaw).digest("hex");
          const retry = await forward(req.url, req.method, headers, patchedRaw); // exactement une réessai
          console.log("[heal] statut du réessai", retry.status, "correction :", JSON.stringify(patched));
          if (retry.ok) {
            upstream = retry;
            body = Buffer.from(await retry.arrayBuffer());
          }
        }
      } catch (err) {
        console.warn("[heal] ignoré :", err.message);
      }
    }

    const out = {};
    upstream.headers.forEach((v, k) => {
      if (!["content-encoding", "content-length", "transfer-encoding", "connection"].includes(k)) out[k] = v;
    });
    res.writeHead(upstream.status, out).end(body);
  })
  .listen(PORT, "127.0.0.1", () => console.log(`proxy auto-correctif sur :${PORT} -→ ${APP}`));

Ce que font les garde-fous

• Une seule réessai. Il n’y a pas de boucle. Si la correction échoue aussi, la réponse d’origine est renvoyée, et le fournisseur voit ce qu’il aurait vu de toute façon.
• Champs protégés. Les identifiants et montants peuvent être re-typés ("4900" en 4900) mais jamais re-valeurs.
• Modifications basées sur l’erreur. Le modèle ne peut toucher que les champs mentionnés dans votre erreur de validation. Cela bloque les réécritures créatives de données non liées.
• Une limite de temps. L’appel au modèle est interrompu après 8 secondes, toute erreur passe à la réponse d’origine.
• Loopback uniquement. Le proxy écoute sur 127.0.0.1, et l’agent du tunnel tourne sur la même machine.

---

5. Prompting et exemple pratique

Le prompt système ci-dessus est volontairement court et restrictif. Gardez en tête trois points quand vous l’adaptez :

1. Décrivez la tâche comme une édition, pas une génération : “changer uniquement les champs mentionnés dans l’erreur.”
2. Donnez au modèle le vrai texte d’erreur de votre app. C’est le signal le plus fiable.
3. Si possible, passez votre vrai schéma JSON dans le champ format pour ancrer le modèle. La documentation sur les sorties structurées d’Ollama recommande aussi de mettre le schéma dans le prompt.

Voici un événement personnalisé hypothétique (pas un vrai événement Stripe) rejeté par un gestionnaire local :

{
  "event": "subscription.updated",
  "data": {
    "customer_id": "cust_99281",
    "amount_due": "4900",
    "status": "active"
  }
}

Le gestionnaire répond avec 422 : ValidationError: amount_due doit être un entier, reçu une chaîne. Champ requis manquant 'currency'. Lors de mon test, le proxy a produit ce corps corrigé et le réessai a réussi :

{
  "event": "subscription.updated",
  "data": {
    "customer_id": "cust_99281",
    "amount_due": 4900,
    "status": "active",
    "currency": "usd"
  }
}

Les deux corrections ne sont pas aussi fiables. Convertir "4900" en 4900 est mécanique. La valeur currency est une supposition. Le modèle n’avait pas d’information que la devise est USD, et la garde a permis la modification uniquement parce que l’erreur mentionnait le champ. En sandbox de développement, cela peut aller. Mais pour tout paiement, des valeurs inventées sont à éviter. Deux mitigations :

• Faites les corrections mécaniques sans modèle. La coercition de type selon un schéma JSON est déterministe et peut précéder. Utilisez le LLM uniquement pour ce qui reste.
• Ne laissez pas le modèle inventer des valeurs requises. Fournissez des valeurs par défaut via la config, ou rejetez la correction et affichez la différence pour revue.

---

6. Signatures : la partie qui casse si vous l’ignore

Les fournisseurs signent les octets bruts du corps de la requête, donc toute modification invalide la signature.

• Stripe envoie un en-tête Stripe-Signature du type t=<timestamp>,v1=<signature>. La signature est une HMAC-SHA256 sur le timestamp et le corps brut. Les bibliothèques clientes rejettent aussi les événements dont le timestamp est hors tolérance, souvent cinq minutes.
• GitHub envoie X-Hub-Signature-256, une empreinte hex HMAC-SHA256 précédée de sha256=. L’ancien en-tête X-Hub-Signature utilise SHA-1 et est conservé pour la compatibilité.

En conséquence, un proxy auto-correctif ne peut pas transmettre la signature originale avec un corps modifié. Une méthode plus sûre que de désactiver la vérification est :

1. Vérifier l’original au bord, contre le corps brut inchangé. La vérification verify-webhook d’ngrok le fait, et vérifie aussi le timestamp pour éviter la rejouabilité. Alternativement, vérifier dans le proxy après la réparation.
2. Réparer, mais seulement après la vérification réussie.
3. Supprimer les en-têtes de signature du fournisseur dans la requête corrigée, et ajouter votre propre signature de développement sur le nouveau corps, plus un en-tête marqueur comme X-Auto-Patched: true. Le schéma ci-dessus le fait.
4. Accepter uniquement la signature de dev en développement. Votre gestionnaire doit vérifier la signature du fournisseur normalement, et accepter la signature de dev uniquement en local. Ne déployez jamais cette dérogation en staging ou en prod.

Cela garantit que seule la trafic authentifiée du fournisseur peut être réparée.

---

7. Sécurité, vie privée, et performance

Ce que “local” protège ou non

Exécuter le modèle localement signifie que les payloads échoués ne sont pas envoyés à une API IA tierce. C’est un vrai avantage si les payloads contiennent des données personnelles. Mais ce n’est pas tout :

• Le fournisseur du tunnel transporte toujours le payload entre lui et votre machine, et peut le logger selon ses réglages.
• Le proxy et le modèle tournent avec vos permissions utilisateur, traitez la machine comme partie de la frontière de confiance.
• Gardez Ollama en boucle locale. La lier à 0.0.0.0 expose un serveur de modèle non authentifié sur votre réseau.
• Envoyer des données à un LLM hébergé soulève des questions de conformité (RGPD, SOC 2, HIPAA), selon vos contrats et la classification des données. C’est une question à poser, pas une violation automatique. Utiliser des données synthétiques ou en mode test en développement évite la question.

Payloads comme entrées non fiables

Un corps de webhook est un texte influencé par un attaquant. Si un champ chaîne contient des instructions, un modèle peut les suivre. Les contraintes de sortie, le garde de diff au niveau du champ, et la liste de champs protégés réduisent le risque, mais ne l’éliminent pas. Ne donnez pas d’outils au modèle, et n’exécutez ni n’interpolez jamais sa sortie ailleurs qu’en JSON.

Latence et délais d’expiration

• Le chargement à froid d’un modèle prend du temps. Ollama garde un modèle en mémoire 5 minutes après la dernière utilisation par défaut, et keep_alive modifie cela.
• GitHub donne 10 secondes au total, donc budgétez l’appel au modèle en conséquence. Le sketch s’interrompt à 8 secondes.
• Si votre gestionnaire est long, envisagez d’accuser réception immédiatement avec un 2xx et de faire le heal et réessayer en arrière-plan. Le compromis est que le fournisseur ne voit plus votre vrai résultat. En développement local, c’est souvent acceptable.

Disjoncteur

Limitez le healing à une tentative par livraison, comme ci-dessus. Si vous recevez des échecs répétés du même type d’événement, arrêtez de le réparer et investiguez. La différence de logs vous indique que votre code ou schéma est obsolète.

---

8. Où ce pattern s’insère, et où non

Ça s’adapte quand :

• vous développez contre un fournisseur et devez faire avancer un flux malgré un décalage de payload ;
• vous souhaitez une preuve automatique et loguée de la différence entre payloads du fournisseur et votre schéma ;
• les corrections sont petites et structurées (types, clés renommées, champs optionnels absents).

Ça ne s’adapte pas quand :

• le système gère de l’argent réel, des droits, ou des décisions de sécurité. Ne “répare” jamais en prod ;
• la vraie correction consiste à fixer la version de l’API du point de terminaison et à faire une mise à jour délibérée. Avec Stripe, testez une nouvelle version avant de déployer, et faites en sorte que la version du webhook corresponde à votre SDK ;
• une transformation déterministe (coercition schéma, ou transformation via une passerelle comme Hookdeck) ferait le boulot sans risque de modèle.

Le bénéfice le plus durable est le log de diff. Chaque patch logué est une trace précise, horodatée, de l’écart entre une API en amont et votre code. Transformez ces entrées en tickets, mettez à jour le gestionnaire ou le schéma, et la étape de réparation n’aura bientôt plus rien à faire.

---

9. Conclusion

Les échecs de webhook en développement viennent surtout de décalages entre ce que le fournisseur envoie et ce que votre gestionnaire accepte. Les fournisseurs ne les réparent pas pour vous. Stripe réessaie jusqu’à trois jours en mode live, et GitHub ne réessaie pas. Un petit proxy qui intercepte les réponses 400/422, demande à un modèle local une correction minimale et conforme au schéma, vérifie cette correction avec des garde-fous, réessaie une fois, et logue la différence peut faire avancer la boucle de développement.

Ce n’est qu’une commodité pour le développement, pas un substitut à des gestionnaires corrects, à des versions d’API fixées, ou à la vérification de signature. Vérifiez d’abord l’original, limitez l’autorité du modèle, considérez tout ce qu’il produit comme une supposition, et utilisez les différences pour corriger le vrai problème.

---

Sources

• Stripe : Webhooks et réessais d’événements
• Stripe : Versioning API
• GitHub : Bonnes pratiques pour l’utilisation des webhooks
• GitHub : Redélivrer des webhooks
• GitHub : Validation des livraisons de webhook
• ngrok : Vérification de la politique de trafic Webhook
• ngrok : Réception et inspection des webhooks localement
• Ollama : Sorties structurées
• Ollama : Bibliothèque de modèles et README
• llama.cpp : Grammaires GBNF
• Hookdeck : Bases et transformations
• Hookdeck CLI