よくある質問

Webhook は署名されていますか？ どう検証しますか？

はい。すべてのリクエストに Signals-Signature: t=<unix seconds>,v1=<hex> が付きます。値は <t>.<raw body> の HMAC-SHA256 で、Webhook の whsec_… シークレットを鍵にします。比較は定数時間で行い、300 秒より古いタイムスタンプは拒否してください。正確な手順は署名を検証するをご覧ください。

なぜ過去のイベントが届かないのですか？

Webhook が送るのは、追加した後に終わった実行だけです。過去分の送信はありません。再開と再度有効にするは違います。止まった位置から続けるので、一時停止中や無効の間に終わった実行も送られます。それより前の履歴を取得するには Pull API を使ってください。

なぜエンドポイントが無効になったのですか？

3 日間一度も配信に成功しないと、Signals は Webhook を無効にします。行に赤いバナーと再度有効にするが表示されます。サーバーが 410 Gone を返したときも、すぐに無効になります。サーバーを修正し、配信履歴を見るで失敗のラベルを確認してから、再度有効にしてください。再度有効にすると、停止した配信がもう一度キューに入ります。再試行と失敗をご覧ください。

自分で一時停止していないのに「この Webhook は Steve チームが停止しました」と表示された場合は、準備ができたら再度有効にしてください。

なぜイベントが重複して届くのですか？

配信は最低 1 回です。サーバーが処理したのにタイムアウトした場合、同じ POST が 2 回届くことがあります。再配信では、同じ実行が新しい webhookId で届きます。処理済みの webhookId の POST と、保存済みの eventId のページ要素はスキップし、重複には 200 を返してください。エンドポイントを冪等にするをご覧ください。

Webhook にイベント本体が入っていないのはなぜですか？

1 回の実行で数千件見つかることもあります。POST は小さいまま（約 1〜2 KB）で、実行の情報と、イベント名ごとの total と firstPageToken だけが入ります。イベントは API キーを使い、GET /api/public/v1/events?pageToken=… で 100 件ずつ読み取ります。実行のイベントを読むをご覧ください。

ページトークンが 410 を返します。どうすればよいですか？

ページトークンの有効期間は 30 日です。代わりに Pull API で実行を読み取ってください。実行の trackerId と、実行より前の since を指定して GET /api/public/v1/events?trackerId=…&since=… を呼び、runId が実行の id と一致する要素だけを残します。再配信では解決しません。再配信できるのは停止した配信と失敗した配信だけで、配信履歴は 30 日間しか残りません。400 はトークンが変更された、または途中で切れたことを示します。404 は API キーが別の組織のものか、Webhook が削除されたことを示します。

イベントはどの順序で届きますか？

保証されません。Signals は Webhook ごとに実行を 1 件ずつ、古い順に送りますが、再試行された POST は新しい POST の後に届くことがあります。ページ内のイベントは sequence の順です。実行をまたいで順序が重要なら detectedAt で並べ替えてください。Pull API は古い順に返します。

なぜ Webhook に LinkedIn エンゲージメントがないのですか？

LinkedIn エンゲージメントは、Webhook では送信されず、Slack にも投稿されません。取得できるのは、source=linkedin_engagement を指定した Pull API と、競合ページの 人物 タブだけです。

なぜ Google 広告で title が null なのですか？

Google の広告透明性センターでは、通常、広告の画像しか表示されません。コピーできる見出しがないためです。title: null と text: null を想定し、media[0].url か previewUrl を使ってください。広告イベントをご覧ください。

Webhook でクレジットは消費されますか？

いいえ。Webhook とそのページは無料です。クレジットを消費するのはトラッカーの実行時で、Signals が Webhook を送るときではありません。

プロジェクトで絞り込めますか？

はい。各 Webhook には、イベント、アクション、競合に並んでプロジェクトフィルターがあります。フィルターが空なら、すべてのプロジェクトが対象です。フィルターは AND で組み合わせます。Webhook はプロジェクトではなく組織に属するため、1 つの Webhook で複数のプロジェクトをカバーできます。すべてのイベントのボディに projectId が含まれます（プロジェクトの導入前に保存されたイベントには含まれない場合があります）。プロジェクトを削除すると、フィルター内のそのエントリは削除されたプロジェクトと表示され、何にも一致しなくなります。

複数の URL にイベントを送れますか？

はい。1 組織につき最大 5 件の Webhook を登録できます。それぞれ独自のフィルターとシークレットを持ちます。2 つの Webhook で同じ URL は使えません。

署名の検証が失敗するのはなぜですか？

ほとんどの場合、次の 3 つのどれかです。生のボディではなく解析後の JSON を検証した、シークレットの再発行後に古いシークレットを使っている、サーバーの時計が 5 分以上ずれている。よくある間違いをご覧ください。

このドキュメントは製品とどう同期していますか？

イベントの形は、製品がペイロードを作るときに使う型定義と同じものから作っています。実データと表示された例は、製品の実際の実行から取得したものです。表示のないものはサンプルです。version フィールドは、互換性を壊す変更のときだけ変わります。Signals はいつでも新しいフィールドを追加することがあるため、未知のキーは無視し、エラーにしないでください。

例に非公開のデータは含まれていますか？

いいえ。例は、公開されている広告や公開レビューなど、実在する競合の公開データを使っています。顧客データ、シークレット、API キーは含まれません。

Webhook と Pull API は併用できますか？

はい。ライブ配信には Webhook、履歴の一括取得やダウンタイム後の追い付きには Pull API を使うチームが多くあります。どちらも同じイベント id を使います。これは Webhook のページの eventId です。