SlingHook

slinghook CLI

SlingHook サーバーが受信した Webhook を、localhost:3000 など、ローカルマシン上のサーバーに転送します。ホスト型の SlingHook インスタンスからは localhost に接続できないため、stripe listen と同じように、CLI が外向きに接続します。

Node 20.17 以降が必要です。

npm install -g slinghook

slinghook auth login --server https://slinghook.co.za
slinghook auth status          # who you're logged in as
slinghook endpoints            # list your endpoint UUIDs
slinghook mcp                  # MCP server for AI agents (see below)
slinghook listen <uuid> --forward http://localhost:3000/webhooks
# <uuid> can also be the catch URL you copied, e.g. https://slinghook.co.za/c/<uuid>

すべてのコマンドは短縮名 shk でも実行できます。たとえば、shk auth login や shk listen <uuid> --forward … のように使えます。以前のバージョンと同じく、login、status、logout は auth を付けずに実行することもできます。

● Listening on endpoint 3f1c…
  Forwarding to http://localhost:3000/webhooks

14:02:11 POST   #1234 → 200 37ms sig:valid
14:02:15 POST   #1235 → ✗ Connection refused (is your local server running?) 2ms

仕組み

1. 認証。 slinghook login は gh auth login と同じように動作します。ログイン方法を選択する画面が表示されます。

   • Web ブラウザー。 CLI に一度限りのコード（BCDF-GHJK など）が表示され、ダッシュボードが開きます。通常の方法（パスワード、Google、GitHub、SAML、二要素認証）でサインインし、コードを承認してください。その後、CLI はコンピューター名を付けた新しい API トークンを受け取ります。このトークンは、承認を行ったワークスペースで使用できます。--web を指定すると、この質問をスキップします。コードの有効期限は 15 分です。
   • 個人アクセストークン。 ユーザー設定 → API トークン（/app/?settings=tokens）で作成し、貼り付けます。スクリプトや CI では、slinghook login --with-token < token.txt、--token shk_… を使用するか、SLINGHOOK_TOKEN を設定してください。

   保存されるのはトークンだけで、保存先は ~/.config/slinghook/config.json（モード 0600）です。サーバーにはトークンの SHA-256 ハッシュのみが保存されます。トークンの確認と取り消しは、ユーザー設定 → API トークンから行えます。

2. ストリーム。 listen は Authorization: Bearer <token> を指定して GET /v1/events/<uuid> を開きます。これはダッシュボードが使用するものと同じ SSE ストリームです。最初の接続時にサーバーは最近の history を送信しますが、CLI はこれをスキップします。転送するのは新しい log イベントだけです。

3. 再接続。 サーバーは仕様上、約 55 秒ごとにストリームを閉じます。CLI は Last-Event-ID を使って再接続するため、切断中に届いた Webhook も順番どおりに一度だけ配信されます。ネットワークエラーが発生した場合、再試行間隔は 1 秒から最大 30 秒まで延長されます。

4. 転送。 各 Webhook は元のメソッド、本文、クエリ文字列、ヘッダーを使って再送信されます。Host や Content-Length など、ホップバイホップヘッダーは除外されます。署名ヘッダーは保持されるため、アプリの検証は実際のリクエストと同様に実行されます。CLI は X-Webhook-Replay: true と X-SlingHook-Log-Id を追加します。配信は一度に 1 件ずつ、タイムアウト 15 秒で行われます。受信時に切り詰められたペイロードはスキップされます。 サーバーが停止している場合、タイムアウトした場合、または 408、425、429、5xx を返した場合、CLI は次へ進む前にさらに 3 回（1 秒後、2 秒後、4 秒後）再試行します。後続の Webhook は待機するため、引き続き順番どおりに届きます。--retries N で回数を変更できます（0～10）。

5. 報告。 各結果は POST /api/logs/<id>/replays に送信され、ダッシュボードの再送履歴に表示されます。これを無効にするには --no-report を使用してください。

チームのルーティング：1 つのプロバイダー URL を複数の開発者で共有

Team プランでは、チーム全体で 1 つのエンドポイントを共有し（Stripe と Shopify が許可する Webhook URL は数個のみです）、それぞれが自分のマシンで自分宛てのイベントを受け取れます。自分宛てのイベントを割り当ててから、--mine を指定してリッスンします。

# Events whose body has metadata.dev = "alice" go to Alice's localhost
slinghook listen <uuid> --forward http://localhost:3000/webhooks \
  --claim data.object.metadata.dev=alice

# Or claim by a header or query parameter
slinghook listen <uuid> --forward http://localhost:3000/webhooks --claim header:X-Dev=alice

--claim はエンドポイントに自分の割り当てを保存し（以前の割り当てを置き換え）、--mine も有効にします。複数の条件を必要とする場合は、繰り返し指定してください。ダッシュボードの エンドポイント設定 → チームのルーティング で割り当てを編集し、その後 --claim を指定せずに listen --mine を実行することもできます。

--mine を指定すると、CLI は自分にルーティングされたイベントだけを転送し、ストリームを開いている間は自分がオンラインとしてカウントされます。誰も割り当てていないイベントは、エンドポイントでオンラインのユーザーに配信する設定になっていない限り、共有フィードに残り、全員が確認できます。この設定が有効な場合は、listen --mine を実行しているユーザーに順番に配信されます。閲覧者はイベントを確認できますが、割り当てはできません。

同じエンドポイントに対して、CLI とダッシュボードの Auto-Relay トグルを同時に実行しないでください。各 Webhook が二重に配信されます。

カオスモード：ハンドラーは冪等ですか？

Pro と Team では、slinghook chaos を使うと、保存済みのシナリオ（またはキャプチャしたリクエスト）を、プロバイダーの実際の動作と同じようにハンドラーへ送信できます。

slinghook chaos <uuid> --forward http://localhost:3000/webhooks --scenario 12 \
  --check http://localhost:3000/debug/orders/count

各イベントは、最初に一度送信されます（ベースライン）。その後、次の順に実行されます。

テスト	送信内容	合格条件
duplicates	すべてのイベントを再度送信	2xx
concurrent	同じイベントを同時に3回送信	すべて2xx
out_of_order	イベントを再度、新しい順に送信	2xx、または再試行を要求する409/425/429/503
malformed	最初の本文を半分に切ったもの、空の本文、不正なデータ	4xx
late_retry	--late-delay 秒後に最初のイベントを再度送信	2xx

配信は署名も含めてキャプチャ時の内容そのままで送信され、X-Webhook-Replay ヘッダーは付加されません。そのため、ハンドラーはプロバイダー自身による再配信と同じように処理します。ステータスコードでは二重の副作用を検出できないため、アプリの状態（注文数や残高など）を返す GET とともに --check を指定してください。ベースラインの後と各テストの後に読み取りが行われ、状態に変化があればそのテストは失敗します。

--only duplicates,concurrent を指定すると、実行するテストを選択できます。--scenario を指定せずに実行すると、エンドポイントのシナリオ一覧が表示されます。レポートはダッシュボード（⌘K →「カオスモード」）に保存されます。また、テストに失敗するとコマンドは終了コード1を返すため、CIで実行できます。

MCP サーバー：AI エージェントでウェブフックをデバッグする

slinghook mcp は Model Context Protocol サーバーです。Claude Code、Cursor、VS Code などの AI コーディングエージェントがこれを バックグラウンドで起動し、あなたとしてログインした状態で、SlingHook を一連のツールとして呼び出します。エージェントに 「Stripe のウェブフックが失敗しています。原因を見つけて修正してください」と頼むと、エージェントは Catch. Debug. Replay の一連のループを実行できます：

ツール	機能	変更を加えますか？
list_endpoints	キャッチ URL と、それぞれの転送先を一覧表示します	いいえ
list_events	キャプチャしたウェブフックの短い概要を表示します（本文は含みません）。すべてのプランで新しい順に 50 件を表示します。query と before_id で全履歴を検索できます（Pro）	いいえ
get_event	1 件のウェブフックの全情報を表示します：ヘッダー、クエリ、本文（長い本文は省略されます）	いいえ
debug_signature	署名が失敗した理由を表示します。候補のシークレットを使った検証もできます	いいえ
replay_event	ウェブフックをあなたのマシンからハンドラーに再送信して記録し、判定結果を返します：修正済み、再発、依然失敗、または引き続き成功	はい：実際に配信します
get_replay_result	リプレイ履歴と修正の検証結果を表示します（どちらのレスポンス本文も Pro のみ）	いいえ
list_scenarios	エンドポイントに保存されたシナリオ（イベントを順序付けたセット）を一覧表示します	いいえ
run_scenario	シナリオの各ステップをあなたのマシンからハンドラーに再送信し、各ステップの結果を報告します（連続して実行するか、keep_timing で記録された間隔を最大 5 秒まで維持します。1 分あたり 3 回まで）	はい：実際に配信します
generate_handler	実際のイベントから型、フィクスチャ、テスト（TypeScript、Python、PHP、Go）を生成し、それを基にハンドラーを構築できます。ファイルは書き込みません	いいえ
compare_events	2 つのウェブフックの違いをフィールドごとに表示します（デフォルトでは同じ種類の直前のイベントと比較します）	いいえ
create_endpoint	新しいキャッチ URL を作成します（同じ名前の場合は既存のものを返します。セッションあたり最大 5 件。チャット経由でシークレットを渡さないでください）	はい：エンドポイントを追加します

すべてのイベントには、アカウント内での番号（#12）が付いており、ダッシュボードの フィードに表示されます。エージェントには、自然な呼び方でイベントを指定できます：「イベント 12」、 「最新のイベント」、「最新の invoice.paid」、または Stripe の evt_1Qx... のようなプロバイダー独自の ID です。インスペクターの #12 メニューから、 そのまま使えるプロンプトをコピーすることもできます。

slinghook login の後に、一度だけ追加します：

# Claude Code (macOS, Linux)
claude mcp add slinghook -- slinghook mcp

# Claude Code on Windows: npm installs slinghook as a .cmd file, which needs cmd /c
claude mcp add slinghook -- cmd /c slinghook mcp

ほかのクライアントでは、同じコマンドを JSON 設定に記述します：

{ "mcpServers": { "slinghook": { "command": "slinghook", "args": ["mcp"] } } }

Claude Code では、/mcp を実行すると接続状態を確認できます。replay_event は 変更を加えるツールとしてマークされているため、エージェントは実行前に確認を求めます。

安全対策：

• リプレイはローカルに限定されます。 replay_event は localhost とプライベート ネットワーク（10.x、172.16-31.x、192.168.x、host.docker.internal）にのみ送信します。ウェブフックの本文は サードパーティーが作成するものであり、細工された本文によって、保存されたペイロードを別の場所に送信するよう エージェントを誘導される可能性があります。この制限を解除するには、サーバーを slinghook mcp --allow-remote-targets で起動してください。
• レート制限。 1 つの MCP セッションで呼び出せるツールは最大 60 回、リプレイは 1 分あたり最大 10 回です。 そのため、ループするエージェントもすぐに停止します。
• 権限。 すべての呼び出しであなたのトークンが使われるため、サーバーのルールが適用されます： あなたのワークスペース、あなたのロール（閲覧者はリプレイできません）、あなたのプランです。

サーバーは stdin と stdout を介して JSON-RPC で通信するため、stdout には何も出力しません。 起動時のメッセージは stderr に出力されます。プロトコルを確認するには、リクエストをパイプで渡します：

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | slinghook mcp

既知の制限

• 本文は JSON イベントストリームをテキストとして通過するため、バイナリペイロードはバイト単位では転送されません。
• 現時点ではリトライはありません。配信に失敗するとその旨が報告され、ダッシュボードからリプレイできます。

開発

SlingHook リポジトリをチェックアウトした状態で、cd cli && npm link を実行すると 作業コピーが PATH に追加され、npm test でテストを実行できます。

公開

package.json の version を更新してから、このフォルダーで npm publish を実行します。まずテストが実行され（prepublishOnly）、パッケージには bin/、src/、この README、package.json のみが含まれます。