イベントリファレンス

イベントの形

Webhook のページで届くすべてのイベントが共通で持つ形。共通キーごとの正確な型、関連性の判定、削除イベント、バージョニングを説明します。

Webhook の POST は、件数とページトークンを持つ小さな実行 Webhook です。イベントはそのページ GET /api/public/v1/events?pageToken=… から、items に最大 100 件ずつ届きます（実行のイベントを読むをご覧ください）。各イベントは 1 つの JSON オブジェクトです。共通フィールド（すべてのイベントで同じ）と、アイテムの詳細を持つプラットフォームオブジェクト 1 つで構成されます。このページでは共通部分を 1 回だけ示します。プラットフォームオブジェクトは、各プラットフォームのページで説明します。

このページの読み方

T | null は、キーが必ず存在し、値が null になることがあるという意味です。optional は、キー自体が存在しないことがあるという意味です。型は TypeScript 風に表記しています。文字列のユニオン型はすべて「開いた」ものとして扱ってください。バージョンを変えずに新しい値が追加されることがあります。

共通フィールド（すべてのイベント）

キーはこの順序で送信されます。

共通フィールド（すべてのイベント）

version

イベントのバージョン。現在は常に数値の 1 です。実行 Webhook には別の version（3、Signals-Event-Version ヘッダー）があります。バージョニングと互換性をご覧ください。

eventId

string

UUID。イベントごとに一意です。重複の排除に使います。

eventType

イベントのファミリー。どのプラットフォームフィールドが含まれるかを決めます。実行 Webhook の eventType も同じファミリーです。

subEventType

string

プラットフォーム。例: google_ad、g2_review、x_post。全部で 18 種類あります。イベントタイプ一覧をご覧ください。

action

'new'|'updated'|'removed'

アイテムに何が起きたか。new は初めて検出されたもの、updated は以前に見たことがあるかもしれないアイテムの変更です。

signalType

string

プロダクトのイベント名。例: reviews.new、social.post、website.changed。全一覧はイベントタイプ一覧をご覧ください。

source

string

イベントを検出したトラッカー: ads、reviews、linkedin、x、instagram、linkedin_mentions、reddit_mentions、news、website、job_postings、competitor_discovery。linkedin_engagement は Webhook では送信されません。

orgId

string

組織の ID。

trackerId

string

イベントを生成したトラッカー（ソース設定）。不透明な ID です。

projectIdoptional

string

トラッカーが属するプロジェクト。キーが存在しないのは、トラッカーがすでに存在せず、かつプロジェクト機能の導入前に保存されたイベントの場合だけです。

runId

string

イベントを検出したトラッカーの実行。UUID です。

competitor

object

トラッキング中の競合: { name: string, domain: string | null, subjectKey: string }。name は表示名です。domain はトラッカーに設定したドメイン（hubspot.com）で、トラッカーがすでに存在しない場合と Webhook のテストイベントでは null です。subjectKey はトラッカーの監視対象を表す内部キーです。内容は不透明なので、解析しないでください。

occurredAt

string|null

アイテムが発生した日時（ISO 8601、2026-10-25T23:50:00.523Z）。ベンダーの公開時刻です。ベンダーが時刻を提供しない場合は、Signals が取得した時刻になります。removed イベントでは null になります（jobs.removed を除く）。

detectedAt

string

Signals が変化を検出した日時（ISO 8601）。

sequence

number

Signals の変更ログ内で増え続ける整数。検出順にイベントを並べ替えるときに使います。

itemKey

string

アイテムの安定した ID。同じアイテムは、new と updated のイベントで同じ itemKey を保ちます。先頭にソース名が付きます。例: reviews-g2-13856432、website-https://www.hubspot.com/pricing、job_postings-7421035。

relevance

object

AI による判定結果。3 つの形のいずれかです。relevanceをご覧ください。

adsResponse | reviewResponse | socialPostResponse | mentionResponse | newsResponse | websiteResponse | jobResponse | competitorResponse

object|null

プラットフォームオブジェクト。この 8 つのキーのうち、eventType に応じてちょうど 1 つだけが含まれます。残りの 7 つは含まれません。removed イベントでは null になります（jobs.removed を除く）。

metadata

object|null

プラットフォームフィールドと同じオブジェクトを、もう一度送信したものです。removed イベントでは null になります（jobs.removed を除く）。

プラットフォームフィールドはちょうど 1 つ

読むべきキーは eventType で分かります: ads → adsResponse、reviews → reviewResponse、social_post → socialPostResponse、mention → mentionResponse、news → newsResponse、website → websiteResponse、jobs → jobResponse、competitor → competitorResponse。metadata は同じ値のコピーです。どちらか一方を読んでください。全プラットフォームを 1 つのコードパスで処理したい場合は、metadata を読みます。

イベント · website_change（完全なイベント）正確な形のサンプル（実データはまだありません）

json

1{
2  "version": 1,
3  "eventId": "df38433d-cc67-4467-ba3a-8892f7a50702",
4  "eventType": "website",
5  "subEventType": "website_change",
6  "action": "updated",
7  "signalType": "website.changed",
8  "source": "website",
9  "orgId": "org_3KikADUjsyXrUJ4RJhWpwcp98Yf",
10  "trackerId": "440b3b16-2000-484a-aa8b-7481d482f1dd",
11  "projectId": "2738158a-08fd-4fc4-912d-43d4c328bc10",
12  "runId": "8ba8ccfa-e9e5-4764-9feb-4b0e88a2ba4a",
13  "competitor": {
14    "name": "HubSpot",
15    "domain": "hubspot.com",
16    "subjectKey": "https://www.hubspot.com/pricing"
17  },
18  "occurredAt": "2026-10-27T15:08:27.064Z",
19  "detectedAt": "2026-10-27T15:08:27.064Z",
20  "sequence": 5,
21  "itemKey": "website-https://www.hubspot.com/pricing",
22  "relevance": {
23    "status": "relevant",
24    "confidence": 1,
25    "reasoning": "HubSpot added HubSpot Credits for Breeze AI agents to its Professional plan. No price changes were detected.",
26    "summary": "HubSpot added HubSpot Credits for Breeze AI agents to its Professional plan. No price changes were detected.",
27    "shortSummary": "Breeze AI Credits Added",
28    "categories": [
29      "feature_update",
30      "pricing_strategy"
31    ]
32  },
33  "websiteResponse": {
34    "title": "HubSpot Pricing",
35    "text": "Title: HubSpot Pricing\n\nURL Source: https://www.hubspot.com/pricing\n\nMarkdown Content:\n# Choose your plan\n\n## Professional\n\nEverything in Starter, plus marketing automation, custom reporting, omni-channel campaigns and HubSpot Credits for Breeze AI agents. …",
36    "url": "https://www.hubspot.com/pricing",
37    "author": null,
38    "media": [],
39    "metrics": null,
40    "pageUrl": "https://www.hubspot.com/pricing",
41    "changes": [
42      {
43        "type": "major",
44        "title": "Breeze AI Credits Added",
45        "description": "Added HubSpot Credits for Breeze AI agents to the Professional plan feature list.",
46        "previous": "# Choose your plan\n\n## Professional\n\nEverything in Starter, plus marketing automation, custom reporting and omni-channel campaigns. …",
47        "current": "# Choose your plan\n\n## Professional\n\nEverything in Starter, plus marketing automation, custom reporting, omni-channel campaigns and HubSpot Credits for Breeze AI agents. …",
48        "categories": [
49          "feature_update",
50          "pricing_strategy"
51        ]
52      }
53    ]
54  },
55  "metadata": {
56    "title": "HubSpot Pricing",
57    "text": "Title: HubSpot Pricing\n\nURL Source: https://www.hubspot.com/pricing\n\nMarkdown Content:\n# Choose your plan\n\n## Professional\n\nEverything in Starter, plus marketing automation, custom reporting, omni-channel campaigns and HubSpot Credits for Breeze AI agents. …",
58    "url": "https://www.hubspot.com/pricing",
59    "author": null,
60    "media": [],
61    "metrics": null,
62    "pageUrl": "https://www.hubspot.com/pricing",
63    "changes": [
64      {
65        "type": "major",
66        "title": "Breeze AI Credits Added",
67        "description": "Added HubSpot Credits for Breeze AI agents to the Professional plan feature list.",
68        "previous": "# Choose your plan\n\n## Professional\n\nEverything in Starter, plus marketing automation, custom reporting and omni-channel campaigns. …",
69        "current": "# Choose your plan\n\n## Professional\n\nEverything in Starter, plus marketing automation, custom reporting, omni-channel campaigns and HubSpot Credits for Breeze AI agents. …",
70        "categories": [
71          "feature_update",
72          "pricing_strategy"
73        ]
74      }
75    ]
76  }
77}

長いテキストはここでは「 …」で省略しています。実際には全文が届きます。

全プラットフォーム共通のアイテム項目

どのプラットフォームオブジェクトも、同じ 6 つのキーで始まります（プラットフォームに platform がある場合は、その後に続きます）。これらはアイテム自体を表します。

アイテム項目 · すべてのプラットフォームオブジェクトに含まれる

title

string|null

見出しまたはタイトル。プラットフォームにない場合は null です（ほとんどの SNS 投稿とレビュー）。

text

string|null

本文。非常に長くなることがあります。ニュース記事は記事本文が Markdown で入ります（100,000 文字で切り詰められます）。Web ページは Markdown の先頭 2,000 文字だけです。

url

string|null

アイテムへの公開リンク。プラットフォームが提供しない場合は null です（ほとんどの Google 広告）。

author

object|null

書いた人、または運営者: { name: string, handle: string | null, url: string | null, imageUrl: string | null }。imageUrl は投稿者の写真で、LinkedIn メンションで LinkedIn が写真を返したときに入ります。それ以外は null です。LinkedIn の写真リンクは数週間で期限切れになるため、保存する場合はダウンロードしてください。不明な場合、author は null です。

media

object[]

画像、動画、ドキュメント: { type: 'image' | 'video' | 'document', url: string }。ない場合は空配列です。メディアのリンクは期限切れになることがあるため、必要なものはダウンロードしてください。

metrics

object|null

プラットフォームが提供した数値そのままで、{ [name]: number } の形です。例: { "rating": 4 }。ない場合は null です。SNS 投稿とメンションでは、同じ数値が名前付きキー（likes、views など）としても繰り返されます。

relevance

Signals は、ほとんどのアイテムをトラッキング対象に照らして判定します。relevance はその結果です。3 つの形があり、status で区別します。

relevance · status: 'relevant'

status

'relevant'

アイテムが判定を通過しました。

confidence

number

0 から 1 まで。判定の確信度です。

reasoning

string

判定がアイテムを残した理由。

summary

string|null

起きたことの短い要約。判定が要約を書かなかった場合は null です。

shortSummary

string|null

summary の 1 行版。ない場合は null です。

categories

string[]

判定が付けたラベル。例: ["Product update/launch"]。自由形式のテキストで、空配列の場合もあります。

relevance · status: 'irrelevant'

status

'irrelevant'

判定がアイテムを除外しました。

confidence

number

0 から 1 まで。

reasoning

string

除外された理由。

関連性なしのアイテムは、イベントとして送信されません。この形を受け取ることはありません。念のため、未知の値として扱ってください。

relevance · status: 'unjudged'

status

'unjudged'

このソースには判定がありません。唯一のキーです。

unjudged になるのは、レビュー、広告、求人、Instagram 投稿、新しい競合です。これらは見つかったまま配信されます。ニュース、LinkedIn、X、メンション、Web ページの変更は判定されるため、relevant になります。

削除イベント

スキーマでは、すべてのプラットフォームで action: "removed" が許可されています。現在 removed を送信するのは、求人トラッカーだけです（jobs.removed。求人の最後に確認できた値が入ります）。そのほかのトラッカーは、イベントを作る前に「なくなった」という変化を除外し、新しい競合の検出は新規の発見だけを報告します。それでも、受信側は removed が来ても壊れないように作ってください。

削除イベントの共通フィールドは同じですが、3 点が異なります（jobs.removed は除きます。プラットフォームフィールド、metadata、occurredAt が残ります）。

occurredAt は null です。
プラットフォームフィールドは null です。
metadata は null です。

イベント · removed（広告、スキーマの定義どおり）正確な形のサンプル（実データはまだありません）

json

1{
2  "version": 1,
3  "eventId": "8db42a9b-7414-40bc-9443-66ac1c6c2002",
4  "eventType": "ads",
5  "subEventType": "meta_ad",
6  "action": "removed",
7  "signalType": "ads.removed",
8  "source": "ads",
9  "orgId": "org_3KikADUjsyXrUJ4RJhWpwcp98Yf",
10  "trackerId": "9aa429da-6540-4f14-a1d8-92526ccf42de",
11  "runId": "c9cd89da-52ef-4803-8669-43a0414bc65f",
12  "competitor": {
13    "name": "HubSpot",
14    "domain": "hubspot.com",
15    "subjectKey": "google:AR10072600183532683265@-|meta:https://www.facebook.com/hubspot|linkedin:hubspot"
16  },
17  "occurredAt": null,
18  "detectedAt": "2026-10-26T08:42:28.926Z",
19  "sequence": 284,
20  "itemKey": "ads-meta-1576853724126416",
21  "relevance": {
22    "status": "unjudged"
23  },
24  "adsResponse": null,
25  "metadata": null
26}

バージョニングと互換性

イベントの version は 1 です。実行 Webhook の version は 3 で、Signals-Event-Version ヘッダーにも入っています。
上がるのは破壊的変更のときだけです。キーの削除、名前の変更、別の型への変更が該当します。
キーの追加は破壊的変更ではありません。新しいキーはいつでも追加される可能性があります。 知らないキーは無視してください。
すべての列挙値（eventType、subEventType、signalType、source、format、categories）は、開いたものとして扱ってください。新しい値が現れることがあります。その値でクラッシュしないようにしてください。
自前のパーサーで、キーの順序に依存しないでください。現在は安定していますが、JSON オブジェクトは順序を持ちません。

イベントタイプ一覧

すべての eventType、subEventType、signalType を 1 つの表にまとめています。

署名を検証する

リクエストが Signals から送られたものか確認します。