セルフヒーリングWebhooks：ローカルLLMsを使った失敗したAPIペイロードの自動リトライと修正

Webhooksは、支払いイベントやリポジトリ通知、内部イベントバスなど、現代システムの同期を保つために不可欠です。しかし、デバッグが面倒な失敗も起こります。ローカル開発環境では、失敗の原因は通常ネットワークではありません。ハンドラーがペイロードを拒否するのは、フィールドの型が間違っている、必須プロパティが欠落している、またはプロバイダーのAPIバージョンがコードの期待と合わなくなった場合です。

この記事では、開発時に使えるパターンを紹介します。トンネルとアプリの間に小さなプロキシを置き、検証失敗（400/422）をキャッチし、ローカルの言語モデルにペイロードの修復を依頼し、一度だけリトライします。これが何を修正できるか、Webhook署名との関係、そして適さないケースについて解説します。2026年10月のドキュメントに基づき、プロバイダーやツールの情報を確認しています。変わることもあるので、信頼する前に再確認してください。

---

1. なぜローカル開発でWebhookが失敗するのか

よくある失敗パターン

1. APIバージョンドリフト。 StripeはWebhookペイロードを特定のAPIバージョンに固定します。 Stripeのバージョニングドキュメントによると、イベントはWebhookエンドポイント作成時に設定されたバージョン、または設定されていなければアカウントのデフォルトを使用します。Stripeのバージョンは日付ベースで、リリース名（例：2024-12-18.acacia、2025-08-27.basil、2026-09-30.endive）が付いています。月次リリースは後方互換性がありますが、新しいメジャーリリースには破壊的変更も含まれます。ローカルの失敗例として、SDKが一つのバージョンを固定しているのに対し、エンドポイントやペイロードが別のバージョンを使っているケースがあります。
2. 型の不一致。 IDや金額が文字列で届き、バリデータが整数を期待している場合や、その逆もあります。
3. フィールドの欠落やリネーム。 必須フィールドが欠落している、または廃止されたキーが置き換えられているケースです。
4. 不正なボディ。 実務では稀ですが、JSONが途中で切れていたり、エスケープが不十分な場合、スキーマチェック前にパースに失敗します。
5. ローカルの厳格さ。 開発用ハンドラーが、プロバイダーのサンプルペイロードに対して書かれたコードよりも厳しく検証している場合があります。

プロバイダーがエンドポイント拒否時に行うこと

プロバイダー	自動リトライ	手動リカバリー
Stripe	ライブモードで最大3日間、指数バックオフ。サンドボックスでは数時間に3回試行。非2xx応答でリトライ。	stripe events resend <event_id> --webhook-endpoint=<endpoint_id> で最大30日間のイベントを再送可能（Stripeドキュメント参照）。
GitHub	なし。失敗した配信の自動再送はしません。	「Recent deliveries」リストやREST APIから過去3日間の配信を再送。

この設計では、2つのポイントが重要です。まず、ペイロードがハンドラーと互換性のないイベントをリトライしても、同じ拒否（422）が繰り返されるだけです。次に、プロバイダー側に「死のレターキュー」は基本的に存在しません。DLQは自分で構築するか、Webhookゲートウェイから得るものです。GitHubは失敗を記録するだけです。

タイミングも重要です。GitHubは2xxの応答を10秒以内に期待し、それを超えると失敗とみなします。Stripeも迅速な2xx応答を求めます。リクエストパスにモデル呼び出しを追加する場合は、これらの制限を守る必要があります。

より簡単なツールから試す

モデルを追加する前に、既存の方法を検討しましょう：

• リプレイ。 ngrokのTraffic Inspectorは、キャプチャしたリクエストをリプレイできます。Hookdeck CLIはイベントをlocalhostに転送し、失敗したイベントをキューに保持し、ダッシュボードやターミナルUIからリトライ可能です。Stripe CLIはstripe listen --forward-to localhost:4242/webhookでローカルエンドポイントに転送できます（トンネル不要）。
• 変換。 Hookdeckの変換は、イベントのペイロード構造やヘッダーを途中で変更します。これはこの記事のビルドの決定版です。
• ハンドラーの修正。 プロバイダーのペイロードが正しく、コードに誤りがある場合は、コード側の修正が最優先です。

LLMによるパッチは、特定の狭いケースで有効です。再生成が難しいペイロードに対してテストを続けたい場合や、ペイロードとスキーマの不一致を示す差分を記録したい場合に役立ちます。

---

2. アーキテクチャ：トンネルとアプリの間のヒーリングプロキシ

トンネルは公開URLからマシンへトラフィックを運びます。ngrokやcloudflaredは、言語モデル呼び出し用に設計されていません。ngrokのTraffic Policyはルールとアクション（例：verify-webhook）に基づいていますし、cloudflaredは一般的なトンネルです。したがって、修復ステップは、あなたが制御する小さなプロキシに置くのが適切です。トンネルエージェントとアプリの間に配置します。

[ Webhook provider ]
        │  POST /webhook
        ▼
[ パブリックトンネルURL（ngrok / cloudflared / その他） ]
        │
        ▼
[ ヒーリングプロキシ  :3001 ] ──(400/422時)──► [ Ollama :11434 ]
        │                                        │
        │◄────────── パッチ済みJSON ───────────────┘
        ▼
[ アプリ  :3000 ]

トンネルはアプリではなく、例としてngrok http 3001やcloudflared tunnel --url http://localhost:3001を指します。

リクエストのライフサイクル

1. プロキシは元のリクエストをそのままアプリに転送します。
2. アプリが2xxまたは400/422以外のステータスを返した場合、そのまま応答します。
3. 400/422かつJSONボディの場合、ペイロードとエラーテキストをローカルモデルに送ります。
4. モデルの出力をガードレール（セクション5）と比較し、違反があればパッチを破棄し、元のエラーを返します。
5. パッチが通れば、一度だけ修正済みのボディでリトライし、成功すればその応答を返します。
6. 差分をログに記録し、コードやスキーマの実際の不一致を修正します。

この仕組みは層ごとに効果的です。ngrokを使う場合、verify-webhook Traffic Policyアクションはエッジでプロバイダーの署名を検証でき、50以上のプロバイダーに対応しています。失敗は403で拒否され、マシンに到達しません。まず検証し、その後修復します。

---

3. ローカルモデルの選択と制約

実行環境とモデル

Ollamaはデフォルトでhttp://localhost:11434にREST APIを提供し、OLLAMA_HOSTを変更しない限り127.0.0.1にバインドします。ループバック上に留めてください。この狭い用途には、小さなモデルで十分です。OllamaのREADMEから一般的な選択肢のパラメータ例：

モデル	パラメータ	ダウンロードサイズ
Llama 3.2	3B	約2.0 GB
Phi-4 Mini	3.8B	約2.5 GB
Gemma 3	4B	約3.3 GB
Llama 3.1	8B	約4.7 GB

「Llama 3」は8Bと70Bのサイズがあります。1Bと3BはLlama 3.2です。Phi-3はライブラリにありますが、Phi-4やMiniに置き換えられています。Gemma 4やQwen 3.5なども追加されています。ollama listを実行し、ペイロードに合った候補を試してください。ハードウェアに依存します。

出力を制約し、検証も行う

OllamaのformatパラメータはJSONスキーマを受け付け、実行時に出力をその形に制約します。 構造化出力のドキュメントでは、スキーマをプロンプトに含めることも推奨しています。これはクラウドサービスではサポートされていませんが、ローカル実行には有効です。llama.cppもjson_schemaリクエストフィールドや手書きのGBNF文法で同じことが可能です。

制約付きデコードは、出力がスキーマに従うことを保証しますが、内容の正確さまでは保証しません。実用的なポイント：

• format: "json"だけではJSONを要求するだけです。小さなモデルでは、スキーマを実際に渡し、結果を検証しましょう。
• temperature: 0と固定のseedを設定します。これにより結果のばらつきは減りますが、完全には排除できません。
• スキーマはモデルに許容される形を伝えますが、値の真偽までは伝えません。

---

4. 最小限のヒーリングプロキシ

以下は依存関係のないNode.js（v20以降）で書かれた例です。あくまでイラストであり、本番コードではありません。モックアプリとモックモデルで動作確認済みです。制御フロー：成功した修復と拒否されたパッチの例です。実際のOllamaモデルとハンドラーで試してください。

// 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]; // 型変換は許容、値の変更は不可

const SYSTEM = `あなたはWebhookのJSONペイロードを修復します。受け取るのは {"payload": ..., "validation_error": ...}。
validation_errorに記載されたフィールドのみ変更してください。IDや金額、タイムスタンプは絶対に変更しないでください。
完全に修正されたペイロードをJSONで返してください。その他は返さないこと。`;

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;
}

// パッチを拒否すべき理由を返す。問題なければ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 "モデルが変更なしのペイロードを返した";
  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 `保護されたフィールドが変更されました: ${p}`;
    if (!errorText.includes(leaf)) return `${p}は検証エラーに記載されていません`;
  }
  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] 拒否:", 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); // 一度だけリトライ
          console.log("[heal] リトライステータス", retry.status, "パッチ:", JSON.stringify(patched));
          if (retry.ok) {
            upstream = retry;
            body = Buffer.from(await retry.arrayBuffer());
          }
        }
      } catch (err) {
        console.warn("[heal] スキップ:", 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(`heal proxy on :${PORT} -→ ${APP}`));

ガードレールの役割

• 一回だけリトライ。 ループはありません。修正後も失敗した場合は元の応答を返し、プロバイダーはそれを見ます。
• 保護されたフィールド。 IDや金額は型変換可能（例："4900"→4900）ですが、値の変更はしません。
• エラーに基づく編集。 モデルは検証エラーに記載されたフィールドのみ変更します。関係のないデータの書き換えを防ぎます。
• 時間制限。 モデル呼び出しは8秒で打ち切り、それ以降は元の応答を返します。
• ループバック限定。 プロキシは127.0.0.1で待ち受け、トンネルエージェントも同じマシン上です。

---

5. プロンプトと具体例

上記のシステムプロンプトは意図的に短く制限的です。適用時に心に留めるべきポイント：

1. タスクは「生成」ではなく「編集」として記述：”エラーに記載されたフィールドのみ変更”。
2. 実アプリのエラーテキストをモデルに渡す。最も信頼できる信号です。
3. 可能なら、formatフィールドに実際のJSONスキーマを渡し、モデルの出力を制約します。

例として、ローカルハンドラーに拒否された架空のStripeイベントを示します：

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

ハンドラーは422を返し、エラーは次の通り：ValidationError: amount_due must be an integer, received string. Missing required field 'currency'.。テストでは、プロキシがこの修正済みペイロードを生成し、リトライに成功しました：

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

この2つの修正は信頼性に差があります。"4900"を4900に変換するのは機械的です。一方、currencyの値は推測です。モデルはUSDであることを知りませんし、エラーに記載されたフィールドだけを変更しています。開発サンドボックスでは問題ありませんが、支払いに関わる場合は、値の偽造は避けるべきです。対策は次の通り：

• 機械的修正はモデルなしで行う。 JSONスキーマに対する型変換は決定論的で、最初に実行可能です。モデルは残りの部分だけに使います。
• モデルに必須値の発明をさせない。 デフォルト値を設定し、currencyの意味を人が決めるか、パッチを拒否して差分をレビューに出す。

---

6. 署名：無視すると壊れる部分

プロバイダーはリクエストボディの正確な生バイト列に署名します。したがって、内容を変更すると署名は無効になります。

• StripeはStripe-Signatureヘッダー（例：t=<timestamp>,v1=<signature>）を送信します。署名はタイムスタンプと生ボディのHMAC-SHA256です。クライアントライブラリは、タイムスタンプが許容範囲外の場合は拒否します（通常5分以内）。
• GitHubはX-Hub-Signature-256（sha256=プレフィックス付きのHMAC-SHA256）を送信します。古いX-Hub-SignatureはSHA-1です。

このため、修復用のプロキシは、修正後のボディに対して署名を通すことはできません。安全なパターンは次の通り：

1. 最初に検証。 署名を変更せずに生のリクエストボディで検証します。ngrokのverify-webhookアクションはこれを行います。
2. 修復。 検証に成功した後に行います。
3. 署名ヘッダーを除去し、開発用署名を付与。 新しいボディに対して自分で署名し、X-Auto-Patched: trueのようなマーカーを付けます。上記のスケッチ例はこれを行います。
4. 開発環境のみで有効。 ハンドラーは通常の署名検証を行い、ローカルでのみ開発署名を受け入れます。本番やステージングには絶対に渡さないこと。

これにより、重要な性質は維持されます：認証済みのプロバイダーのトラフィックだけが修復される。

---

7. セキュリティ、プライバシー、パフォーマンス

「ローカル」が守る範囲

モデルをローカルで動かすと、ペイロードはサードパーティのAI APIに送信されません。個人情報を含む場合にメリットがあります。ただし、完全ではありません：

• トンネル提供者はペイロードを運び、設定によってはログに記録します。
• プロキシとモデルはあなたのユーザ権限で動作します。マシンは信頼の境界の一部です。
• Ollamaはループバックに限定してください。0.0.0.0にバインドすると、未認証のモデルサーバがネットワークに公開されます。
• データをホスト型LLMに送ることは、契約やデータ分類次第でコンプライアンス問題になる場合があります。開発中はテストデータや疑似データを使うのが安全です。

ペイロードは信頼できない入力

Webhookのボディは攻撃者の操作によるテキストです。文字列フィールドに指示が書かれていると、モデルがそれに従う可能性があります。出力制約やフィールドレベルの差分ガード、保護フィールドリストはリスクを低減しますが、完全ではありません。ツールを渡さず、出力をJSONの範囲内だけで使うこと。

レイテンシとタイムアウト

• モデルのコールドロードには時間がかかります。Ollamaはデフォルトで最後の使用から5分間モデルをメモリに保持します（keep_aliveで変更可能）。
• GitHubは合計10秒の制限があります。healは8秒で中断します。
• ハンドラーが長時間かかる場合は、即座に2xxで応答し、バックグラウンドで修復とリトライを行うことも検討してください。これにより、実ハンドラーの結果は見えなくなりますが、開発には許容範囲です。

サーキットブレーカー

一つのイベントにつき一度だけ修復を試みる（上記と同じ）。繰り返し失敗する場合は修復をやめ、原因を調査してください。差分ログは、コードやスキーマの古さを示す証拠です。

---

8. このパターンの適用範囲と不適合例

適用できる場合:

• プロバイダーと連携し、ペイロードの不一致を自動的に修正したい場合
• プロバイダーのペイロードとスキーマの差分を記録したい場合
• 小さな構造的修正（型、リネーム、必須フィールドの欠落）

適さない場合:

• 実際の金銭やセキュリティ決定を扱うシステム。運用中のペイロード修正は避ける。
• APIバージョンの固定と意図的なアップグレードが最優先。Stripeでは新バージョンをテストし、WebhookエンドポイントのバージョンをSDKと一致させる。
• schemaの強制変換やゲートウェイ変換（Hookdeckのような）で十分な場合は、モデルリスクを避けられます。

最も長続きするメリットは差分ログです。各修正は、APIとコードの不一致を正確に記録したタイムスタンプ付きの証拠です。これらをチケット化し、ハンドラーやスキーマを更新すれば、修復は不要になります。

---

9. まとめ

開発中のWebhook失敗は、プロバイダーが送る内容とハンドラーが受け入れる内容の不一致がほとんどです。プロバイダーは修正しません。Stripeは最大3日間同じペイロードをリトライしませんし、GitHubはリトライしません。400/422に対してキャッチし、ローカルモデルに最小限の修正を依頼し、ガードレールで検証し、一度だけリトライし、差分を記録する小さなプロキシは、開発ループを維持できます。

これは開発の便宜のためのものであり、正しいハンドラーや固定されたAPIバージョン、署名検証の代替ではありません。最初に検証し、モデルの権威を限定し、出力は推測とみなす。差分を使って問題を修正しましょう。

---

参考資料

• Stripe: Webhooks and event retries
• Stripe: API versioning
• GitHub: Webhookのベストプラクティス
• GitHub: Webhookの再送
• GitHub: Webhook配信の検証
• ngrok: Verify Webhook Traffic Policy
• ngrok: Webhookのローカル受信と検査
• Ollama: 構造化出力
• Ollama: モデルライブラリとREADME
• llama.cpp: GBNF文法
• Hookdeck: 基礎と変換
• Hookdeck CLI