mcpField
R
receive-webhooks

receive-webhooks

github.com/ngrokクラウド・DevOps18145 回インストール4 日前に更新
リポジトリ

receive-webhooks について

receive-webhooksは、ローカルテストや本番環境で、ngrok経由の受信Webhookをエッジで署名検証するスキルです。検証済みのリクエストをローカルポートまたは内部の受信サービスへ転送し、アプリケーションでの署名検証コード作成を不要にします。

主な機能

  1. 01ngrokエッジでプロバイダー署名を検証
  2. 02有効なリクエストをローカルポートへ転送
  3. 03リクエストを内部の受信サービスへ転送
  4. 04パスごとに複数プロバイダーをルーティング
  5. 05Vaultまたは環境変数でシークレットを保管

活用シーン

  1. 01受信Webhookをローカルでデバッグ
  2. 02本番の受信サービスを公開インターネットから隔離
  3. 03単一ゲートウェイで複数のWebhookプロバイダーに対応
  4. 04システム到達前に無効な署名を拒否

MCP 対応

ngrok MCPサーバーを使ってVaultやシークレットを作成し、Traffic Inspectorのリクエスト記録を照会できます。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/ngrok/skills --skill receive-webhooks

インストール後、Claude Code で/receive-webhooksを入力して読み込まれたか確認します。

同梱ファイルreferences/providers.md

詳細

Webhook を受信する

受信した Webhook を受け取り、ngrok のエッジでプロバイダーの署名を検証して、ユーザーのサービスに配信します。検証コードを書く必要はなく、必要に応じてサービスを公開せずに利用できます。

始める前に

認証が必要です（ngrok-setup）。この作業では Traffic Policy を使用します。ngrok-engine から verify-webhook と forward-internal の仕組み、およびエンドポイントの選択方法を確認してください。

基本パターン（すべてのケース）

2 つのアクションを順に実行します。

  1. verify-webhook - 署名を検証します（enforce: false でない限り、検証に失敗すると 403 を返して拒否します）。
  2. 配信 - テストではローカルポートに配信し、本番では forward-internal でプライベートな受信先に転送します。
on_http_request:
  - actions:
      - type: verify-webhook
        config:
          provider: stripe
          secret: "${secrets.get('webhooks', 'stripe-signing-secret')}"
      - type: forward-internal
        config: { url: https://billing.internal }

プロバイダーの一覧、プロバイダーごとのシークレット設定、リプレイ保護、エンドポイント検証チャレンジについては、references/providers.md を参照してください。

構成を選ぶ

  • ローカルでのテスト／デバッグ -> ローカルポートに転送するエージェントエンドポイントを使用します。最も手早く設定できます。検証後、forward-internal ではなくポートに配信します。
  • 本番／プライベート／規制対象／共有ゲートウェイ -> 検証とルーティングのポリシーを実行するクラウドエンドポイント（パブリックで常時稼働）を使用し、受信先をパブリックインターネットから隔離する内部エンドポイントに転送します。この構成でクラウド＋内部エンドポイントを使う理由は、ngrok-engine を参照してください。

適用する

ポリシーをアタッチし、ユーザーが利用する環境でエンドポイントを起動します。詳しくは ngrok-surfaces を参照してください。ポリシーの本文はどの環境でも同じで、異なるのはアタッチ方法だけです。

プロバイダーの Webhook 設定に貼り付ける公開 URL をユーザーに伝えてください。

シナリオ例（仕組みは同じで、重点が異なります）

  • 「受信先をパブリックインターネットから隔離したい。」 クラウドエンドポイントがエッジで検証し、forward-internal で内部にバインドされた受信先に転送します。インバウンドのファイアウォールポートは不要です。エージェントは 443 経由でアウトバウンド接続します。
  • 「規制対象／コンプライアンスに準拠した配信が必要です。」 基本構成に加えて、シークレットは平文ではなく Vault に保管し、署名はシステムに到達する前に検証します。また、同じポリシーに IP 許可リストや JWT チェックを追加できます。検証に失敗した場合は拒否されます。
  • 「すべてのプロバイダーに対応するゲートウェイを 1 つにしたい。」 1 つのポリシーに、パスでルーティングする複数のルール（/stripe、/github など）を設定します。それぞれのルールでプロバイダーを検証してから適切な内部サービスに転送するため、サービスごとのコードではなく、検証、ルーティング、シークレットを 1 か所で管理できます。

動作を確認する

  • プロバイダーのダッシュボードからテストイベントを送信するか、有効な署名ヘッダーを付けて curl を実行します。
  • 有効なリクエスト -> 上流に到達します。無効なリクエスト -> エッジで 403 を返します。
  • エージェントの Web インスペクター（デフォルトは http://localhost:4040）またはダッシュボードの Traffic Inspector で、受信した各リクエストの正確なヘッダーと本文を確認します。

エージェント向けの注意事項

  • 署名検証コードを書くようユーザーに伝えないでください。verify-webhook で置き換えられることが、この仕組みの要点です。
  • 署名シークレットをハードコードしないでください。Vault または環境変数を使用してください。
  • 署名シークレットをチャットに貼り付けるようユーザーに求めないでください。また、その方法で提示されたシークレットも受け取らないでください。ユーザー自身に Vault または環境変数へ設定してもらい、ポリシーから参照してください。ngrok-surfaces の「Account resources」で ngrok MCP サーバーを選択した場合は、gw_create_vault で Vault を作成し、gw_create_secret でシークレットを作成します。シークレット用ツールでは、値を入力するためのダッシュボードフォームがユーザーに表示されるため、API キーは不要です。それ以外の場合は、ダッシュボードまたは ngrok api secrets create を使用してください。トランスクリプトに記載された whsec_... は漏えいしたシークレットです。
  • 本文を書き換える処理を verify-webhook より前に実行してはいけません。署名チェックが失敗するためです。
  • ngrok MCP サーバーに接続されている場合、gw_query_traffic_inspector でプロバイダーのリクエストが到着したか、エンドポイントが何を返したかを確認できます。受信先のデバッグを始める前に確認してください。

コメント

Markdown 対応