Webhook の仕組み

Webhook は、トラッカーの実行で新しいイベントが見つかったことを、あなたの URL に知らせます。ポーリングは不要です。あなたは HTTPS エンドポイントを用意します。Signals はそこに小さな実行 Webhook を 1 回 POST し、あなたは 2xx を返します。イベント本体は、その後 API から 100 件ずつ読み取ります。

リクエスト

Webhook と実行の組み合わせごとに POST を 1 回。Content-Type: application/json

ボディ

実行 Webhook（version は 3）。実行の情報と、イベント名ごとの total、totalPages、firstPageToken。イベント本体は入りません。約 1〜2 KB

イベント

API キーで GET /api/public/v1/events?pageToken=…。1 ページに完全なイベントが最大 100 件。実行のイベントを読むをご覧ください

タイミング

チェック完了から数分後。一致するイベントがない実行では何も送られません

スコープ

組織ごと。エンドポイントは最大 5 件

フィルター

イベント、アクション、競合、プロジェクト。空ならすべて。AND で組み合わせ

配信

最低 1 回。POST は webhookId、各イベントは eventId で重複を排除してください

コスト

無料。Webhook でクレジットは消費しません

送信されないもの

LinkedIn エンゲージメント（Pull API のみ）

送信される内容

トラッカーのチェック 1 回が 1 つの実行です。実行が終わり、フィルターに一致するイベントが 1 件以上あると、Signals はその実行について Webhook に POST を 1 回送ります。POST には、イベント名ごとの件数と、イベントを読み取るためのトークンが入ります。

広告トラッカーの実行の例です。ネットワークごとに 1 件ずつ、合計 3 件の新しい広告が見つかったため、ads.new に bySubEvent があります。ads.updated は 0 として載っています。

1{
2  "version": 3,
3  "webhookId": "7fc0937d-6f0f-56c3-b6cf-5090cbb43015",
4  "type": "run.completed",
5  "eventType": "ads",
6  "sentAt": "2026-10-27T20:29:55.624Z",
7  "run": {
8    "id": "b0b5b63b-fc3d-4eef-84ab-879e2335c06d",
9    "trackerId": "3c8918c2-7011-4518-9185-31344c83861f",
10    "projectId": "2738158a-08fd-4fc4-912d-43d4c328bc10",
11    "source": "ads",
12    "completedAt": "2026-10-27T20:29:00.624Z",
13    "competitor": {
14      "name": "HubSpot",
15      "domain": "hubspot.com",
16      "subjectKey": "google:AR10072600183532683265@-|meta:https://www.facebook.com/hubspot|linkedin:hubspot"
17    }
18  },
19  "pageSize": 100,
20  "events": {
21    "ads.new": {
22      "total": 3,
23      "totalPages": 1,
24      "bySubEvent": {
25        "google_ad": 1,
26        "meta_ad": 1,
27        "linkedin_ad": 1
28      },
29      "firstPageToken": "<page token: ads.new, page 1>"
30    },
31    "ads.updated": {
32      "total": 0,
33      "totalPages": 0,
34      "firstPageToken": null
35    }
36  }
37}

例のトークンはプレースホルダーです。実際のトークンは不透明な文字列です。解析したり変更したりしないでください。

ファミリーごとのイベント名

セクションのキーはイベント名（各イベントの signalType）です。各名前は 1 つのアクションに対応します。実行には、そのファミリーのすべての名前がこの順で載り、見つからなかった名前は total: 0 になります。

8 つのファミリーと 18 のサブタイプです。

• removed の名前を送るのは求人だけです（jobs.removed、終了した求人）。他のトラッカーは送らないため、その実行 Webhook には removed のセクションがありません。
• website.page_added は total: 0 として載ります。現在、Web サイトの実行に入るのは website.changed だけです。
• bySubEvent が入るのは広告とレビューの実行で、複数のネットワークやサイトが見つかったときだけです。
• engagement.*（LinkedIn エンゲージメント）は Webhook では送られません。

求人の実行では、3 つのアクションすべてが載ります。

1{
2  "version": 3,
3  "webhookId": "ab78fcb4-5d5d-5224-9bc7-1a7025550b24",
4  "type": "run.completed",
5  "eventType": "jobs",
6  "sentAt": "2026-10-29T06:03:07.903Z",
7  "run": {
8    "id": "5d2f7a14-9c3b-4e68-8f21-b7c4a0e19d36",
9    "trackerId": "b13a7c58-02d4-4e9f-8a61-5f3c9e0d2b74",
10    "projectId": "2738158a-08fd-4fc4-912d-43d4c328bc10",
11    "source": "job_postings",
12    "completedAt": "2026-10-29T06:02:12.903Z",
13    "competitor": {
14      "name": "Acme",
15      "domain": "acme.com",
16      "subjectKey": "jobs:acme.com"
17    }
18  },
19  "pageSize": 100,
20  "events": {
21    "jobs.new": {
22      "total": 1,
23      "totalPages": 1,
24      "firstPageToken": "<page token: jobs.new, page 1>"
25    },
26    "jobs.updated": {
27      "total": 1,
28      "totalPages": 1,
29      "firstPageToken": "<page token: jobs.updated, page 1>"
30    },
31    "jobs.removed": {
32      "total": 1,
33      "totalPages": 1,
34      "firstPageToken": "<page token: jobs.removed, page 1>"
35    }
36  }
37}

ページの各イベントはイベントの形で、version は 1 です。イベントタイプ一覧に、サブタイプごとのプラットフォームフィールドが載っています。

イベントを読み取る

1curl "$SIGNALS_HOST/api/public/v1/events?pageToken=$TOKEN" \
2  -H "x-api-key: $SIGNALS_API_KEY"

レスポンスの items に最大 100 件のイベントと、nextPageToken が入ります。nextPageToken が null になるまで呼び続けます。レスポンスの全項目、エラー、そのまま使えるループは実行のイベントを読むにあります。

受け取るイベント

各 Webhook には 4 つのフィルターがあります。フィルターが空なら「すべて」を意味します。フィルターは AND で組み合わせます。イベントは 4 つすべてに一致する必要があります。フィルターは POST の件数と、ページのイベントの両方に適用されます。たとえば google_ad だけに絞った Webhook では、ads.new は Google 広告だけになります。total は Google 広告の件数で、ページにも Google 広告だけが入ります。

種類をまるごと選ぶと、そのすべてのサブタイプが送られます。サブタイプを選ぶと、種類の中で絞り込めます。実行のイベントが 1 件も一致しなければ、その実行の POST は送られません。

Webhook を追加ダイアログのイベントフィルター

届くまでの流れ

1 つのエンドポイントへの配信は 1 件ずつ、古い実行から送られます。応答の遅いエンドポイントは、後に続く実行を遅らせます。

ヘッダー

すべてのリクエストに、次のヘッダーが付きます。

配信の保証

• 最低 1 回。 同じ POST が複数回届くことがあります。たとえば、サーバーは受け取ったのにタイムアウトになった場合です。webhookId で重複を排除してください。
• イベントのキーは eventId。 再配信では、同じ実行が新しい webhookId で送られます。また、同じページを 2 回読むこともあります。各イベントは eventId で重複を排除してください。
• 順序は保証されません。 実行は古い順に送られますが、再試行された POST は新しい POST の後に届くことがあります。ページ内のイベントは sequence の順です。実行をまたいで順序が重要なら detectedAt で並べ替えてください。
• 一時停止しても位置は保たれます。 再開や再度有効にするの後、その間に終わった実行も送られます。新しい Webhook に届くのは、作成した後に終わった実行だけです。それより前の履歴は Pull API で読み込んでください。
• リダイレクトには追従しません。 最終的な URL を Signals に登録してください。
• 無料。 Webhook とそのページでクレジットは消費しません。