Webhook が破綻しやすい理由
- 未検証 JSON は不正ジョブやパース例外を招きます。
- 弱い認証 は URL 流出時に即悪用されます。
- 受信 Mac 直実行 は共有キューを迂回し可視性が失われます。
マルチノードデプロイガイドと骨格を揃えます。
検証・認証・起動・通知の対照
層分離で差し替えが局所化されます。
| 層 | 目的 | 実装の型 |
|---|---|---|
| 検証 | 不正形を先に弾く | スキーマでイベント・参照・コミット・冪等キーを必須化 |
| 認証 | 送信元を証明 | ベアラ共有秘密または生ボディ HMAC を定数時間比較、任意で IP 制限 |
| 起動 | どのノードでも同じ共有ビルド | 正規化レコードを中央キューまたは API に一度だけ投入 |
| 通知 | 横断可視化 | HTTPS・バス・Incoming 等へノード ID とビルド ID |
設定ステップ
- 単一 HTTPS ルートを公開し相関 ID をログと応答に載せる。
- 検証してから副作用。型・長さ・列挙のみ許可し未知イベントは拒否。
- トークン／ HMAC を定数時間比較し秘密は保管庫注入。
- 正規化タスクを中央キューへ。全 MeshMac ワーカーが同じレコードを dequeue。
- 待機・実行・成功・失敗で通知アダプタを同一 IF から呼び、本文は短文に留める。
- 永続化後すぐ応答、重処理は非同期で数十秒制限を避ける。
数値目安
- 上流タイムアウトは概ね十〜三十秒想定でハンドラは数秒以内。
- 冪等キーは二十四〜七十二時間保持し再送でも二重起動を防ぐ。
- 通知 POSTは数秒タイムアウトと指数バックオフ三回程度。
HTTP エラー早見
コード意味を揃えないと再試行が誤爆します。
| コード | 想定原因 | 確認 |
|---|---|---|
| 400 | 破損・必須欠落 | スキーマ差分・文字コード・プロキシ改変 |
| 401 / 403 | 秘密不一致 | ヘッダ綴り・ローテ・署名対象・許可 IP |
| 404 | パス誤り | location・末尾スラ・メソッド |
| 408 / 504 | 遅延 | 同期処理・プール枯渇・DB ロック |
| 429 | レート | バースト間隔・共有出口・バックオフ |
| 5xx | 例外・下流障害 | スタック・キュー・秘密注入・相関 ID ログ |
まとめ
四層分離で多ノードでも同じ運用パターンに揃います。実機は MeshMac レンタルで即用意し、ホームから料金と申込へ進めてください。