Webhookの概要
Listings APIがアカウントのイベントをサーバーにプッシュ通知する仕組み、イベントの種類、各配信が満たす必要がある5つの条件について説明します。
変更の有無を確認するために API をポーリングすると、コストがかかり、検知にも必ず多少の遅延が生じます。Webhook では通知の方向が逆になります。アカウントで何かが起きると（レビューの受信、拠点の編集、Google Business の投稿の公開など）、Listings API が数秒以内に、JSON リクエストボディを含む HTTP POST を管理下の URL に送信します。
Webhook URL はアカウントごとに1つで、イベントごとの購読設定はありません。アカウントで Webhook が有効になっており、エンドポイントの検証が完了していれば、このページに記載されているすべてのイベントがその1つの URL に配信されます。event フィールドで処理を分岐し、不要なイベントは無視してください。
配信パイプライン
受信できるイベント
6つのグループに計18のイベントがあります。各イベントは REST API ですでに管理しているリソースに対応しているため、Webhook で変更がいつ発生したかを確認し、エンドポイントで何が変わったかを確認できます。
すべてのフィールドの表とペイロードの例は、イベントリファレンスにあります。
対象外
プラットフォームは他のイベントグループも発行しますが、対応する REST エンドポイントがここでは公開されていないため、Listings API のドキュメントおよびサポートの対象外です。記載漏れと誤解されないよう、以下に示します。
- レビューキャンペーン：
campaign.* - ランキング：
rankings.* - Social投稿とブースト：
social_post.* - Social接続：
social_connection.* - AI による投稿アイデア：
idea.*、idea_series.*、idea_pipeline.*、idea_image.* - Google Business Profile のオーナー権限：
gbp_ownership.*
実装前に確認する2つの注意点
配信の判定条件
配信には5つの条件があり、記載順に確認されます。最初に満たさなかった条件で配信が停止し、それ以降の条件は確認されません。
プランと上限
Webhookは、Launch、Growth、Enterpriseのすべてのプランで利用できます。トライアルには選択したプランが適用されるため、トライアルアカウントでは初日からそのプランの上限内でWebhookを利用できます。利用権限はプランに紐づいているため、即時ではなくプラン変更の一環として付与または削除されます。アップグレードをクリックした瞬間ではなく、次回のプラン変更または新規登録時の同期で反映されるものと考えてください。ダッシュボードのWebhookページには、現在の利用権限と上限が表示されます。
配信数は1分あたりと1日あたりの上限に対しても計測され、どちらの上限もプランに応じて設定されます。
Webhookの上限はプランのAPIリクエスト上限と同じです。こちらから送信するイベント数の割り当ては、こちらに送信できるリクエスト数の割り当てと等しくなります。
アカウントに上限が適用されるのは、プランの制限値が配信処理に同期された後です。それまでは確認する上限が存在しないため、配信数の計測もイベントの破棄も行われません。そのため、新規作成直後のアカウントでは、プランの上限が適用される前に、配信数が計測されずに配信が行われる場合があります。rate_limitedがないことを、上限を下回っている証拠と解釈しないでください。
配信数の計測の動作：
- 独立した2つの固定時間枠があります。1つは1分単位、もう1つは1日単位です。Webhookには1時間単位の時間枠はありません。（リクエストのレート制限は、異なる時間枠を持つ別のシステムです。両者で割り当てを共有することはありません。）
- 時間枠は暦に合わせた固定区間であり、スライディング方式ではありません。分単位のカウンターは毎分の境界で、日単位のカウンターはUTCの日付の境界でリセットされます。
- 上限を超えるとイベントは破棄されます。 キューへの追加、遅延配信、再試行は行われません。送信経路のどこにも再試行キューはなく、
429を返す呼び出し元も存在しません。配信の試行は配信ステータスrate_limitedで記録されるため、イベントの消失を確認できます。 - 制限処理が失敗した場合は配信を許可します。 制限処理自体が判定を返せない場合、配信は破棄されずに実行されます。計測処理の障害によってイベントが失われることはありません。
イベント生成側に組み込まれている唯一の配信量制御は、profile.updatedのデバウンス処理です。配信は拠点ごとに60秒間で最大1回で、時間枠の開始時に行われます。同じ拠点に対する短時間の連続した編集は1つのイベントにまとめられ、受信するchanged_fieldsには、その時間枠を開始した編集のみが記述されます。それ以外にはデバウンス処理は適用されません。
配信は時間枠の開始時に行われるため、イベントは60秒の時間枠の開始時点に届きます。その到着をきっかけにデータを読み直しても、最初の編集しか確認できません。時間枠が終了した後、イベントから少なくとも60秒が経過した時点で2回目の読み直しを行うようにし、イベント自体の配信は1回しか試行されず再試行もないため、タイマーで拠点データの整合性も定期的に確認してください。受信できなかったイベントからの復旧を参照してください。
設定手順
- HTTPSエンドポイントを用意します。 パブリックに名前解決でき、有効な証明書を備え、
POSTを受け付け、5秒未満で2xxを返す必要があります。プライベートアドレスと内部アドレス（ループバック、RFC-1918、リンクローカル、クラウドメタデータのIPアドレス）は拒否されます。 - ダッシュボードのWebhookページでWebhook URLを保存します。1つのアカウントにつき1つのURLを使用し、すべてのイベントをそのURLに送信します。
- 署名用シークレットを生成し、サーバーに保存します。シークレットは1度だけ表示されます。この時点から配信に署名が付与され、検証が必須になります。
- エンドポイントを検証します。 プラットフォームが署名付きチャレンジを送信し、エンドポイントはnonceのHMACを16進数形式で返します。成功すると、エンドポイントが検証済みになり、配信が開始されます。正確な仕様と動作するコードについては、署名と検証を参照してください。
- イベントを処理します。 署名を検証し、ペイロードをキューに入れ、
200を返します。実際の処理はリクエスト処理の外で実行してください。タイムアウト、配信試行を1回のみとするポリシー、重複と順序に関する動作については、配信の動作を参照してください。
次に参照するドキュメント
- 署名と検証：
X-ListingsAPI-Signatureヘッダー、生のリクエストボディを使用するルール、ハンドシェイクについて説明します。 - 配信の動作：標準ペイロード、5秒のタイムアウト、再試行しない理由、すべての配信ステータスについて説明します。
- イベントリファレンス：全18イベントをフィールドごとに説明します。