この記事の要点
- パース前に暗号で止める： 定時間の HMAC（または mTLS）、クロックずれ窓、リプレイ用ノンスは「JSON の形を信じてから検証」より堅い。
- 実行は隔離： Webhook ワーカーは不透明な作業単位を durable キューへ書くだけにし、Runner は private キューから引き取る。ペイロード由来のシェルを HTTP プロセスに直結させない。
- べき等はデータ契約： 安定した
event_id、重複排除ストア、ジッタ付きの上限付きリトライ。二重配送はログ一行ではなくメトリクスで見える化する。 - 監査列は「退屈」に： 誰がどの Runner リースでどのアーティファクト digest を回したか——HTTP ログ、キュー、CI の標準出力で列名を揃える。
1. 低信頼の受信検証
すべての POST を、暗号検証が通るまで信頼できないバイト列として扱います。生ボディ（JSON 変換前）に対して署名を検証し、タイムスタンプ欠落は拒否、Date または X-OpenClaw-Timestamp についてサーバ側の短いスライディング窓でスキューを抑えます。署名不良は 401、エンベロープ破損は 400 に分けてアラートを分割してください。TLS がエッジで終端する場合、検証がエッジかアプリかを文書化しておかないと、遅延封じの名目で検証が迂回されます。
送信元 IP と署名鍵 IDの双方でレート制限し、鍵流出時の面積を抑えます。ログにはシークレットや生ペイロードは出さず、切り詰めたフィンガープリントだけを残します。HTTP 境界でのアイデンティティ固定は、ビルド成果物でのアイデンティティ固定と同列の規律です。Apple 側の署名をクラウド CI で揃えているチームなら、同じ発想を取り入れてください。詳細は Apple Silicon クラウド Mac での iOS/macOS CI：codesign、Notarization、stapler とキーチェーン境界——再現可能なパイプラインと拒否コード早見表 が参考になります。
2. 実行分離：ゲートウェイ → キュー → Runner
Webhook ハンドラは最小限に留めます。検証と内部スキーマへの正規化、durable キューへの書き込み、相関 ID 付きの 202 返却まで。重い git fetch、pod install、xcodebuild は、許可したレジストリへ egress が限られた短命の Runner リース側で実行してください。Webhook フィールドからシェルを直接起動しないのは必須要件です。
バーストが Runner の温まり速度を超えるとキュー深が先に悪化します。補助コンテナや bind mount を併用する場合は、ホストのディスクとマウント境界を先に揃えないとジョブは途中で静かに壊れます。境界の読み方は Apple Silicon クラウド Mac で本番相当の Docker：arm64/amd64 イメージ、bind mount とビルドキャッシュのトラブルシュート手順（プランのリソース境界つき） がわかりやすいです。Runner がトンネル越しにあるなら、ゲートウェイと同じ DNS／MTU 前提かを早期検証してください。往復経路と分割 DNS の要点は WireGuard とゲートウェイのペアリング：国境をまたぐ遠隔操作のトラブルシュート（MTU、非対称経路、DNS 分岐、遅延観測とクラウド Mac のリージョン・スペック選び） にまとめています。
3. べき等リトライとポイズンメッセージ
配送は少なくとも一度（at-least-once）と仮定します。event_id（または正規化ペイロストのコンテンツアドレス化ハッシュ）を必須にし、TTL をリトライ地平に合わせた重複排除テーブルへ結果を保存します。クライアント側の再試行は指数バックオフ＋ジッタ、サーバ側は二重目を最初の成功と同形の HTTP で短絡させ、上流の突き合わせを単純に保ちます。
キューごとに最大受信回数を設け、原本エンベロープを添付したデッドレターを別ストリームへ逃がします。ポストモーテムには内側 JSON だけでなく署名メタが必要です。duplicate_suppressed と validation_failed を別カウンタに分けると当番手順が短く済みます。
4. 可観測性と監査フィールド（早見）
HTTP のアクセスログ、キュー行、Runner の標準出力に同じ識別子を運びます。最低限そろえておく列は次のとおりです。
| フィールド | 置き場所 | 監査・障害対応で効く理由 |
|---|---|---|
trace_id / correlation_id |
エッジ、アプリ、キュー、Runner | タイムスタンプ結合だけに頼らず E2E で再構成できる |
event_id + delivery_attempt |
Webhook、DLQ | 重複抑制とリトライ方針の証跡になる |
signing_key_id |
検証器、監査ログ | 鍵ローテと侵害時の爆半径を説明できる |
runner_lease_id / ホスト種別 |
スケジューラ、CI メタデータ | 自動化と容量 SKU の対応づけに使える |
git_ref / アーティファクト digest |
ビルド記録 | セキュリティレビューでの再現性の根拠になる |
policy_version |
ゲートウェイ設定スナップショットのハッシュ | 昨日は通ったのに今日拒否された理由を説明できる |
構造化 JSON ログは散文より優れています。状態遷移（received / enqueued / leased / succeeded / failed_terminal）ごとに一行。Webhook 派生フィールドに PII を載せず、アクターは IdP 上の不透明 ID に写像してください。
リトライ下でも歪まないメトリクス
Webhook 面には RED 系を閉じます：レート、4xx と 5xx に分割したエラー率、エンキュー境界の遅延（E2E ビルド時間とは別）。キューの最古メッセージ滞留と Runner 忙閑も分離して見ないと、「入口は健全だが容量が枯渇」か「検証が CPU を食い潰している」かを誤診します。重複抑制と DLQ 深さは単発スパイクではなく持続増でアラートしてください。アウト後の再試行バーストは正常系です。
5. まとめ
Webhook チェーンが壊れる典型は地味です。時刻ずれ、二重配送、ゲートウェイとブート直後の Runner で DNS ビューが食い違う、といった事象です。ビルド分単位の最適化より先に検証、enqueue 専用ハンドラ、べき等、共有相関 ID を設計へ焼き込むと、OpenClaw の自動化がセキュリティレビューと深夜三点の自分双方に読みやすくなります。
クラウド Mac なら分離 Runner と安定した到達経路の運用が楽になる
Apple Silicon は Xcode とシミュレータに十分なユニファイドメモリを与え、macOS は開発者に馴染み深い Unix ツールチェーンと launchd 向けの自動化に適しています。Webhook が長大な CI に枝分かれするときほど、個人端末を Runner 代わりに回すより専用のクラウド Mac mini容量の方がキュー深の予測と鍵境界の固定がしやすくなります。Gatekeeper や SIP など macOS の防御線も、雑多なノードより説明しやすいセキュリティ物語になります。
Webhook 起点のビルドを、サイズとロックダウンが明確なハードへ載せ替えたいなら、kvmboot のクラウド Mac mini M4 は現実的な第一歩です——プランと料金を確認することで、OpenClaw の自動化が頼りにできるキュー P95 を狙いやすくなります。