2026 OpenClaw Webhook 受信実務：Mac VPS での署名検証・リプレイ防止・冪等検収チェックリスト（FAQ）
OpenClaw を Mac VPS に常駐させたあとも、チケットや決済、社内承認は構造化 JSON を HTTP で押し込みたい場面が残ります。IM 公式コネクタだけでは主キー設計と噛み合わず、自作 Webhook にすると HMAC の生バイト一致、時刻窓、指数バックオフ付き再送、ゲートウェイ JSONL との相関を自分で揃える必要があります。本稿はプラットフォーム／SRE 向けに痛み分け、HTTP と IM の意思決定表、TLS・リバプロ前提、ヘッダ設計表、五段階ロールアウト、三つの運用指標、層別切り分けと既存記事リンク、FAQ までを一連の Runbook にまとめます。多チャネル運用は 検収記事、ゲートウェイは doctor ガイド を参照してください。
目次
1. 痛み分け：署名ドリフト・リプレイ・冪等の穴
Webhook は信頼の根をベンダ OAuth から自前 HTTP に移します。ペイロードは整いますが、正規化・時計・重複排除・観測は自前です。
- 署名ドリフト：API ゲートが JSON を再整形すると署名側と検証側のバイト列が一致せず断続 401 になります。
- 時刻とリプレイ：署名だけではキャプチャ再送が通ります。窓が狭すぎるとリージョン跨ぎのスキューで正常再送も落ちます。
- 冪等の欠落：決済やチケットは指数バックオフ再送が前提です。event_id の短期ストアが無いと危険ツールが二重発火します。
- 観測の断線：requestId を JSONL に載せないと openclaw doctor 結果と結べず原因が散ります。
2. 意思決定表：HTTP Webhook とネイティブ IM
ヒューマンループが Feishu／Telegram に既にあるなら マルチチャネル Runbook を先に。ERP／決済／マイクロサービス発なら HTTP が短いです。
| 観点 | HTTP Webhook | ネイティブ IM |
|---|---|---|
| 信頼根 | 自前 HMAC または mTLS、鍵バージョン明示 | プラットフォーム OAuth／Bot トークン |
| 冪等と再送 | ストアと再送嵐メトリクスが必須 | 重複も起きるがチャット意味論に沿う |
| トポロジ | 固定グローバル IP・証明書・パス設計が要る | 主に外向き長接続、家庭用 NAT には不向き |
| 典型用途 | チケット状態、決済結果、CI 結果プッシュ | メンション付き会話、サポート補助 |
3. Mac VPS 前提：TLS・リバプロ・ポート
Nginx や Caddy で TLS を終端し、ループバックの sidecar へ転送します。寛い CORS と広い時刻窓を素の公開リスナに出さないでください。文書上のゲートウェイポートは 18789、コンテナ管理面は 3000 など混在しがちなので外向き path と upstream を変更票に固定し、アップグレード後に再測定し doctor 記事 と突き合わせます。証明書は自動更新とフルチェーンをリバプロ層に。追加で Docker トークン Runbook と ワンクリック導入の手引き を読み、CLI とデーモンの環境変数を揃えます。
4. HMAC と時刻窓：パラメータ表
ヘッダ名はチームで差し替え可ですが「生 body 一致」と「時刻窓」は削れません。
| 項目 | 推奨値 | メモ |
|---|---|---|
X-Webhook-Timestamp |
Unix 秒またはミリ秒 | 検証済みサーバ時刻との差が窓内か |
X-Webhook-Signature |
v1=<hmac_hex> |
ローテ中に複数秘密を並行検証するための接頭辞 |
X-Webhook-Id |
ULID など一意イベント ID | 冪等キー。TTL はベンダ再送上限＋余白 |
| 窓幅 | 初期 ±300 秒など | NTP と地域 RTT を見てから締める |
TS=$(date +%s)
BODY='{"type":"ticket.updated","id":"01JVM0EXAMPLE"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | awk '{print $2}')
curl -sS -X POST "https://your-mac-vps.example/hooks/openclaw" \
-H "Content-Type: application/json" \
-H "X-Webhook-Timestamp: $TS" \
-H "X-Webhook-Signature: v1=$SIG" \
-H "X-Webhook-Id: 01JVM0EXAMPLE" \
-d "$BODY"
5. 五段階：鍵ローテから curl プローブまで
- URL 固定：DNS・証明書・パスを同じ変更票に載せ、連携中に path を変えない。
- 版付き検証：
v1で材料選択。旧秘密は検証のみで窓が閉じるまで残す。 - 冪等ストア：Redis や SQLite に TTL。ヒット率をメトリクス化して黙殺を防ぐ。
- 観測整列：合法 Webhook 後に webhookId と gatewaySession を JSONL へ。
- 五プローブ：正常、期限切れ時刻、誤署名、重複 Id、巨大 body。HTTP コードとログ行を添付資料に。
6. 三つの運用指標
本番宣言前に三カウンタを仕込み、支払い事故の夜にログ尾だけを見ない運用へ。
- 時計スキュー：Mac VPS で NTP を確認。三十秒超が続くなら窓を広げる前に時刻を直す。
- リプレイ窓外拒否率：ゼロ付近が正常。上昇はバルクリプレイかプロキシ古 body の疑い。
- 重複 Id ヒット率：決済ピークで数パーセントから十数パーセントも普通。常にゼロなら冪等が死んでいる可能性。
7. 層別切り分けと内部リンク
200 なのにエージェントが動かないときは chunked 改変→アプリキュー詰まり→ゲートウェイのツール拒否→モデル 429 の順で、各層で同一 requestId に戻れるかを確認します。ノート PC常駐や家庭回線は固定出口とスリープ方針が弱く TLS 曲線と再送統計が悪化し、監査で求められる「どの鍵でどのコールバックを誰が検証したか」の証跡が途切れがちです。Docker は柔軟ですがボリューム権限とネットワーク抽象が一段増え、インシデントが長引きます。7×24 で OpenClaw と監査付き HTTP 入站を両立するチームには、VPSMAC の Apple Silicon Mac クラウドで時計・帯域・SSH 運用を一本化し、リバプロ・署名・JSONL を同一 Runbook に載せる方が、縁の下の端末にルールを積むより本質に近いことが多いです。
8. FAQ
401 最初に？ 署名バイト列一致、その後タイムスタンプと v1 接頭辞。
IM と HTTP 併用？ 冪等接頭辞を分け同時到達を前提にゲートウェイで統一去重。
企業プロキシ？ launchd と Compose の HTTPS_PROXY／NO_PROXY を揃え同一文脈で curl。
9. まとめ
成功は HTTP 200 ではなく署名・冪等・JSONL を一つの証拠鎖にできるかです。五段階と三指標をテンプレに入れ、重複 Id をページングへ、四半期ごとに鍵ローテ演習を回してください。