SteveSignalsDocs
EN日本語

Webhook

Webhook を設定する

エンドポイントを作り、開発者ページで追加し、署名シークレットをコピーし、ページを読むための API キーを作って、テストイベントを送ります。Clay、Zapier、n8n の例を含みます。

このガイドでは、何もない状態から、自分のエンドポイントで検証済みのテスト配信を受け取るまでを説明します。所要時間は 15 分ほどです。

組織の管理者またはマネージャーのロールが必要です。それ以外のメンバーは Webhook を表示できますが、変更はできません。

エンドポイントを作る

署名を検証し、すばやく応答する小さな HTTPS サーバーを用意します。

Webhook を追加する

開発者 → Webhook → Webhook を追加。

フィルターを設定する

受け取りたいイベント、アクション、競合、プロジェクトを選びます。すべて空のままでも構いません。

署名シークレットをコピーする

表示は一度だけです。アプリのシークレットとして保管してください。

API キーを作る

エンドポイントは、このキーでイベントを 100 件ずつ読み取ります。

テストイベントを送る

行のメニューからテストイベントを送信を使います。

配信履歴を確認する

配信済み と、ステータス 200 を確認します。

1. エンドポイントを作る

エンドポイントは次の 5 つを行う必要があります。

  1. JSON を解析する前に、生のリクエストボディを読み取る。
  2. Signals-Signature の署名を検証する。
  3. その webhookId を処理済みなら、リクエストをスキップする。
  4. ボディを保存し、10 秒以内に 200 を返す。
  5. バックグラウンドジョブで、イベント名ごとにページを読み取り、各イベントを eventId をキーに 1 回だけ保存する。実行のイベントを読むをご覧ください。

署名シークレットは SIGNALS_WEBHOOK_SECRET、API キーは SIGNALS_API_KEY という名前の環境変数に保存します。どちらもステップ 4 と 5 で取得するので、最初はプレースホルダーのままで構いません。

生のボディを使う

フレームワークが先に JSON を解析し、それを再シリアライズすると、バイト列が変わって署名の検証に失敗します。生のバイト列を読み取ってください。よくある間違いをご覧ください。

エンドポイントは、公開された HTTPS の URL（例: https://your-app.com/signals-hook）にデプロイします。次のルールを満たさない URL は、Signals が拒否します。

ルール理由
https:// で始まる単なる http:// は受け付けません。
ポート 443:8443 などのカスタムポートは拒否されます。
公開ホスト名localhost、*.local、*.internal は拒否されます。
IP アドレスは不可https://203.0.113.7/… は拒否されます。
ワイルドカード DNS は不可nip.io、sslip.io などは拒否されます。
ユーザー名とパスワードは不可https://user:pass@host/… は拒否されます。
最終的な URLリダイレクトは追従しません。

自分のノート PC からテストするには、ポート 443 の公開 https ホスト名を提供するトンネルサービスを使ってください。

2. Webhook を追加する

サイドバーで開発者を開きます。ページには API キーと Webhook があります。

開発者ページ
開発者ページには、API キーと Webhook があります（画面は英語版）。

Webhook で Webhook を追加をクリックし、エンドポイント URL を入力します。

Webhook を追加ダイアログ
Webhook を追加ダイアログ。最初に URL、次にフィルターです。

3. フィルターを設定する

URL の下にフィルターがあります。ダイアログには「フィルターを空にすると、すべての値が送信されます。」と表示されます。

  • イベント: 種類とサブタイプ。デフォルトはすべてのイベント。
  • アクション: new、updated、removed。デフォルトは 3 つすべて。
  • 競合: 検索できるリスト。デフォルトはすべての競合。
  • プロジェクト: 検索できるリスト。デフォルトはすべてのプロジェクト。

フィルターは AND で組み合わせます。POST の件数と、ページのイベントの両方を決めます。後から編集で変更できます。Webhook の仕組みをご覧ください。

Webhook を追加をクリックします。

4. 署名シークレットをコピーする

保存すると、Signals が署名シークレットを表示します。whsec_ で始まります。パネルには「このシークレットは二度と表示されません。今すぐ保管してください。」と表示されます。

シークレットをコピーをクリックし、アプリに SIGNALS_WEBHOOK_SECRET として保存してから、完了をクリックします。紛失した場合は、シークレットを再発行を使ってください。

シークレットはパスワードと同じように扱ってください。git にコミットしないでください。シークレットを知っていれば、誰でもあなたのエンドポイントに偽のリクエストを送れます。

5. API キーを作る

POST にはイベント本体が入っていません。エンドポイントは GET /api/public/v1/events?pageToken=… でイベントを読み取ります。これには同じ組織の API キーが必要です。

開発者 → API キーでキーを作成をクリックし、エンドポイントにちなんだ名前を付けて、SIGNALS_API_KEY として保存します。API キーを作成するをご覧ください。

6. テストイベントを送る

行のメニュー（Webhook の操作）を開き、テストイベントを送信を選びます。

Webhook の行メニュー
行のメニュー: テストイベントを送信、配信履歴を見る、編集、シークレットを再発行、一時停止、削除。

Signals がテストの実行をキューに入れます。1 分以内に届きます。このテストには、次の特徴があります。

  • 実際のものと同じ形の、署名付きの実行 Webhook で、reviews.new が total: 1 である。
  • firstPageToken がサンプルの G2 レビューを 1 件返すので、ページのループも試せる。
  • Signals-Test: true ヘッダーが付く。
  • 有効な Webhook にのみ送られ、同時に待機できるテストは 1 件だけである。

業務ロジックでテスト配信をスキップするには、Signals-Test を使ってください。

7. 配信履歴を確認する

行のメニューから配信履歴を見るを選びます。テストが成功すると配信済みと表示され、ステータスコード 200、ミリ秒単位の時間、1 / 9 回目 が示されます。

配信履歴シート
各行は、あなたの URL への POST 1 件、つまり 1 つの実行です。件数、ステータス、コード、所要時間が表示されます。

行が失敗または**停止（再配信可能）**になっている場合は、エラーのラベルを見て原因を修正してください。再試行と失敗をご覧ください。

これで、トラッカーがチェックを終えるたびに、実行ごとに 1 回の POST が届きます。

ノーコードツールでの設定

Zapier、Clay、n8n は、ほかのクライアントと同じように POST を受け取ります。ただし、多くは生のボディを公開しないため、HMAC 署名を検証できません。

署名を検証できない場合

URL を秘密にし（それが唯一の保護です）、ボディのキーで絞り込み、URL が漏れたら変更してください。数行のコードを実行できるなら、代わりに署名を検証してください。

どのツールでも、POST は実行にイベントがあることを知らせるだけです。x-api-key ヘッダー付きで GET /api/public/v1/events?pageToken=… を呼ぶ HTTP ステップを追加し、items をループしてください。ほとんどの実行は 1 ページに収まります（totalPages: 1）。複数ページの場合は、nextPageToken が null になるまで HTTP ステップを繰り返します。

Clay

Webhook テーブルを作る

Clay で Webhook からテーブルを作り、その URL をコピーします。標準ポートの https URL であることを確認してください。

Signals に追加する

URL を Webhook を追加に貼り付け、フィルターを設定します。

ページを読む

各 POST は 1 行として届きます。HTTP API 列を追加し、必要なイベント名のトークン（例: events["jobs.new"].firstPageToken）でページの URL を呼びます。items の各要素を別のテーブルに書き込み、competitor.name、signalType、metadata を列にマッピングします。

Zapier

Catch Hook で Zap を作る

トリガー: Webhooks by Zapier → Catch Hook。カスタム Webhook URL をコピーします。

Signals に追加する

URL を Webhook を追加に貼り付けます。

ページを取得する

テストイベントを送り、Zapier で Test trigger をクリックします。トークンと x-api-key ヘッダーを使って、ページの URL に Webhooks by Zapier → GET ステップを追加します。続けて items に Looping by Zapier ステップを追加し、Zap をイベントごとに実行します。

n8n

Webhook ノードを追加する

HTTP メソッドは POST。ワークフローを有効にしたら、テスト URL ではなく Production URL を使います。

すばやく応答する

Respond を Immediately にして、Signals が 10 秒以内に 200 を受け取れるようにします。

イベントをページごとに読む

x-api-key ヘッダー付きで、ページの URL に HTTP Request ノードを追加し、ページネーションを有効にします。次の URL は nextPageToken から作り、空になったら止めます。items に Split Out ノードを追加し、続けて {{ $json.signalType }} に IF ノードを追加します。
実行のイベントを読む

ページのレスポンス、エラー、ループ。

署名を検証する

正確なアルゴリズムとよくある間違い。

テストと管理

一時停止、再発行、再配信、管理 API。

前へ
実行のイベントを読む
次へ
署名を検証する