前提条件
- モニターアクセス権のあるPubrio APIキー
- パブリックにアクセス可能なHTTPSエンドポイント（またはusewebhook.comのテストURL）
ステップ1：ウェブフック配信先でモニターを作成
headers オブジェクトは毎回の配信にカスタムHTTPヘッダーを追加します（認証に便利）。body オブジェクトはウェブフックペイロードのルートレベルにカスタムフィールドを追加します。
ステップ2：ウェブフック接続を検証
ウェブフック検証エンドポイントを使用してエンドポイントが到達可能かテストします。これはプレースホルダーデータを含むサンプルペイロードを送信します — クレジットは消費されず、実際のシグナルは取得されません。ステップ3：実データでテスト
接続が検証されたら、プロセストライエンドポイントを使用して実際の実行をトリガーします。これは実際のシグナルを取得しウェブフックに配信します —tried_at に最近の過去の日付を使用してデータが利用可能であることを確認してください：
validateと異なり、tryエンドポイントは実際のスキャンを実行しクレジットを消費します。実際のペイロードが正しく届くことを確認し、スケジュールされたスキャンが開始される前に結果をすばやく推定するために使用してください。
ステップ4：シグネチャの検証
各モニターには、受信ペイロードがPubrioからのものであることを確認するための一意のシグネチャがあります。x-pubrio-signature（上で取得したシークレット）と x-pubrio-signature-256（そのシークレットを鍵にした生のリクエストボディの HMAC-SHA256、16 進数）。JSON を解析する前に、受信した生のバイト列で HMAC を検証してください。
ウェブフックペイロード構造
ペイロードはモニターのdetection_mode に応じて異なります：
- シグナルファースト
- カンパニーファースト
signal_first モードでは、ペイロードにトップレベルの signals 配列が含まれます：destination_config のカスタム body フィールドはルートレベルに表示されます（例：上記の例の "pipeline": "my-webhook"）。拡大シグナル
jobs、news、advertisements に加えて、モニターは拡大シグナル — 企業が新しい市場へ参入・拡大していることを示す日付付きの証拠 — を監視できます。signal_types に expansions を追加するだけです。
froms と tos に加えて、stages、scopes、momentum、freshness、signal_types、signal_subtypes、signal_strengths、source_types、window_days があります。有効なスラッグは Expansion Reference から取得してください。
Webhook はモニターのレコード単位で拡大シグナルを配信します。デフォルトの
signal 単位（signal_first）では各エントリが 1 件の生シグナル（HIRE、AD、OFFICE…）で、その companies[0] が（企業、市場）カードを持ち、country_code が市場です。record_unit: "company" を設定すると企業ごとに 1 件、シグナルはネストされます。メールダイジェストは常に企業と市場でグループ化されます。クラウドフットプリント
DNS はクラウドフットプリントのシグナルです（企業がある市場でクラウド／ホスティング基盤を立ち上げること）。拡大フィルター内の signal_types でモニターを絞り込みます。
evidence_url が含まれます。基盤の生データがペイロードに含まれることはありません。 同じホストをプロバイダー・リージョン・都市のフィルター付きの純粋なイベントストリームとして受け取るには、下記の専用シグナルタイプ cloud_footprints を使います。
拡大シグナルのペイロード
クラウドフットプリントシグナル
signal_types に cloud_footprints を加えると、企業が本国以外の市場に立ち上げたホストごとに 1 レコードを受け取れます。クラウドやホスティング事業者上の新しいサーバー、またはリージョンや国を移動したサーバーです。拡大シグナルの DNS が読むのと同じインフラ証拠ですが、市場ステージではなく純粋なイベントストリームとして配信されます。すべてのホストを到着順に、フットプリント独自のフィルターで、ステージ・スコア・ウィンドウなしで届けます。
各
signal には provider、cloud_region、city、novelty、country_code、country_name、event_date、ローカライズされた display_label（例 AWS · Frankfurt）、evidence_url が含まれます。生のホスト名や IP アドレスは決して含まれません。本国市場のインフラはこのストリームには含まれません。
配信ルール
レコードとは
レコードは各上限が数える単位であり、配信エントリ 1 件です。デフォルトは検出モードに従います：signal_first はシグナルを配信（求人・広告・記事・拡大シグナルごとに signals[] 1 件）、company_first は企業を配信（企業ごとに companies[] 1 件、シグナルはネスト）。record_unit で明示的に選べます。例えば signal_first の広告モニターに record_unit: "company" を設定すると、広告ごとではなく広告主ごとに 1 件配信されます。
企業の除外
excluded_companies（および companies と同じ方法で解決される excluded_domains・excluded_linkedin_urls）は配信しない企業のリストです。除外企業は両方の検出モードでエンリッチメントと課金の前に取り除かれ、company_first のウォッチリストもリストにある間はその企業をスキップします。モニターあたり最大 100,000 社で、既存顧客の CRM エクスポートに収まります。 Update Monitor で companies_mode または excluded_companies_mode を add / remove にすると、送った項目だけが変わり、リスト全体を送り直す必要はありません。
上限
どんな大きさのリストもページ単位で読み出せます。Company Search に
company_groups: [source_group_id]（または excluded_group_id）を渡してください。どちらの ID も Lookup Monitor が返し、同エンドポイントはリスト全体も返します。
最新を優先
既定ではモニターは到着順（古いものから）に配信し、上限を超えた分は次回に繰り越されるため、その日の積み残しが新しいシグナルより先に処理されます。is_newest_first: true を設定すると逆になり、各実行で最新の一致レコードを配信し、上限で漏れた分は永久にスキップされ、キューには残りません。これはすべてのシグナルタイプに適用され、一時停止や日次予算の枯渇から再開したモニターにも適用されます。
重複排除と再配信
- シグナルが 2 回配信されることはありません。 成功した配信はすべて、運んだシグナルのキーを記録し、各実行はその記録にある候補を全シグナルタイプで落とします。求人・ニュース・広告はタイプごとのカーソルも保持するため、配信済みシグナルは再取得すらされません。
company_dedupe_days: Nは、同じ企業が N 日間に最大 1 回の配信にしか現れないことを保証します（モニターの全シグナルタイプ横断）。ウィンドウ内のその後のシグナルはスキップされます。- すべてのペイロードに
metadata.monitor_log_id（その試行の統計ログ行）とmetadata.parent_monitor_log_id（初回はnull、再試行時は自動でも再試行処理経由でも初回の ID）が含まれます。同じシグナルがもう一度届くのはこの再試行だけなので、parent_monitor_log_id || monitor_log_idで重複排除してください。 再試行は既定で初回のペイロードをそのまま再送します。is_use_original_payload: falseを送ると、まず現在のルール（除外リストと 2 つの台帳）を再適用し、何も残らなければコード40085でスキップされます。
メール配信先
メール配信を希望するチームは、destination_type を "email" に設定してください：
Pubrioはエージェンシーやチーム向けのホワイトラベルメール配信をサポートしています。送信者ドメインとブランディングのカスタマイズについてはお問い合わせください。
トラブルシューティング
ウェブフックがペイロードを受信しない
ウェブフックがペイロードを受信しない
障害後にモニターが一時停止
障害後にモニターが一時停止
ウェブフックが一貫して非200コードを返す場合、
max_failure_trigger の連続失敗回数に達するとモニターが一時停止します。問題を修正し、モニター更新で再アクティベートしてください。重複ペイロード
重複ペイロード
配信に失敗しリトライが設定されている場合、同じペイロードを複数回受信する可能性があります。
triggered_at またはログIDを使用して重複排除してください。ペイロードが大きすぎる
ペイロードが大きすぎる
max_records_per_trigger を減らして配信ごとのレコード数を制限してください。フィルターを絞り込んでマッチするシグナル量を減らすこともできます。