イベント サービスのドキュメント (Webhook)
プラットフォームからイベントペイロードを受信する方法
Table of Contents
変更履歴
2024年1月
デザインとAPIの変更
- Webhook は、設定全体で 1 つの URL のみに限定されなくなりました。代わりに、すべての Webhook に固有の宛先 URL を設定できます。
- Webhooks に専用の API エンドポイント ( /api/sales-partners/webhooks)が追加されました
- 以前は、 PUT /api/sales-partners/$idエンドポイントによって設定され、
pushUrl
とsubscribedWebhookEventTypes
が渡されていましたが、これはサポートされなくなりました。
- 以前は、 PUT /api/sales-partners/$idエンドポイントによって設定され、
新しいウェブフック
イベント タイプの定義セクションで説明されている新しい Webhook を導入しました。
- リストデータポイントが無効です
- ブランドデータポイントチェック
- ディレクトリ_ビジネス_ページ_データ_ポイント_無効
- 位置情報の提案
既存のWebhookの変更
データ ポイントの処理を効率化するためのパラメータを追加しました。
LISTING_DATAPOINT_CHECK
– 新しいデータポイントをリッスンするときに、新しいデータポイントがどれであるかも受け取るようになりました。これにより、後から直接クエリを実行できます。
- ブールフィールド
newDatapointsFound
、新しいデータポイントが見つかったかどうかを示します。 - 配列
newDataPointIds
は、新たに取得された各データポイントのIDをリストします。同じロジックがBRAND_DATAPOINT_CHECK
にも適用されます。 - 配列
updatedDataPointIds
は、更新された既存のデータ ポイントの情報が含まれます (例: エンド ユーザーが顧客レビューを変更した場合)。
イベントサービスとは何ですか?Webhookとは何ですか?
Webhookは、何かが発生した際にアプリから送信される自動メッセージです。プラットフォームのイベントサービス(Webhook)により、プラットフォームと他のアプリケーション間のリアルタイム通信が可能になります。位置情報の変更、ビジネスリスティングの更新、ソーシャルメディアでのインタラクション(レビューなど)の変更など、登録済みのイベントについて、指定されたURLにHTTP POSTリクエストを送信することで機能します。このシームレスな統合により、動的な変化に関する最新情報を常に把握し、リアルタイムデータの転送を容易に行うことができます。
変更が発生したときにのみリアルタイムのpingを取得するのに役立ちます
サービスの設定
このサービスは 2 つの方法で設定できます。
プラットフォームのインターフェースから設定する
これが最も簡単な方法です。プラットフォームに管理者ユーザーとしてログインし、組織設定に移動すると「Webhooks」タブが表示されます。ここで、Webhookごとに指定のターゲットURLを追加したり、利用可能なWebhookを確認したりできます。
APIセットアップ
Webhook は API によって設定することもできます。
サポートされているWebhookの種類
下記で詳しく説明する様々なWebhookをご用意しています。ユースケースに応じて、1つまたは複数のWebhookをご利用ください。
現在サポートされているイベント タイプ (Webhook) を理解するには、次のエンドポイントをクエリします。
curl --location 'https://$yourdomain.com/api/sales-partners/subscribable-event-types' \
--header 'privateKey: $privateKey'
Webhookの購読
新しいWebhookを設定するには、次のクエリを実行してください。同じWebhookを複数の送信先( pushUrl
)に送信できます。
curl --location 'https://$yourdomain.com/api/salespartners/webhooks' \
--header 'privateKey: $privateKey' \
--data '{
"pushUrl" : "https://webhook.site/e84ba9cc-d56f-4e30-9607-cd3ddc65952f",
"type" : "LISTING_DATAPOINT_CHECK"
}'
イベントタイプの定義
アプリケーションは次のイベント (Webhook) を提供します。
タイプ |
説明 |
リスト同期チェック | リスティングの同期チェックが行われました(ステータスリスティングの変更の可能性を含む) |
リストリンクの変更 | リストのURLが変更されました |
リストの更新 | リストのデータをディレクトリに送信しようとしました |
リストステータスの変更 | リスティングのステータスが手動で変更されたことを示します。これは稀にしか発生せず、多くの場合はオペレーションチームまたはエンジニアリングチームによる手動チェックの結果です。 |
リストデータポイントチェック | リストの新しいデータポイントが見つかったか、既存のデータポイントに変更がありました |
リストデータポイントが無効です | リストデータポイントがディレクトリから削除されたため、これも無効にしました |
ディレクトリ_ビジネス_ページ_データ_ポイント_チェック | ブランドページの新しいデータポイントが見つかりました |
ディレクトリ_ビジネス_ページ_データ_ポイント_無効 | ブランドデータポイントがディレクトリから削除されたため、これも無効にしました |
場所_作成 | 場所が作成されました |
場所ステータスが変更されました | 場所のステータスが変更されました |
ロケーションプロファイルが変更されました | ユーザーによって場所が更新されました |
ビジネス製品計画の変更 | 企業(およびその後続の拠点)が製品計画を変更した |
ビジネス作成 | ビジネスが設立されました |
ターゲットURLとサブスクライブするイベントは実行中に変更できます。イベントの送信に失敗した場合、システムは数回再試行した後、イベントを破棄します。
ペイロードの外観
ペイロードの基本構造は次のとおりです。イベントの種類とロードの詳細については、「フィールドの説明」と「イベント」を参照してください。
{
"event": {
"comment": "Location profile has been updated",
"id": 2926113683,
"location": 636605,
"time": "2018-11-05T17:35:07.000+01:00",
"type": "LOCATION_PROFILE_CHANGED",
"user": "user@test.com"
},
"signature": "X"
}
すべての JSON ペイロードには、常にイベント フィールドと署名フィールドが含まれます。
フィールドの説明
イベント
イベントはプラットフォームで発生した変更を表し、実際のペイロードとして機能します。イベントの種類によって異なります。主なフィールドには以下が含まれますが、これらに限定されません。
分野 | 説明 | コメント |
id | 送信されるイベントの一意のID | イベントが2回処理されないようにするために使用できます |
時間 | イベントが発生した時刻 | |
タイプ | イベントの種類 | 可能な値については下記の説明を参照してください |
リスト | イベントが関連するリスティングのID | |
位置 | イベントが関連する場所のID | イベントに反応して、例えば変更後に新しい位置データを取得するために使用できます。 |
仕事 | イベントに関連するビジネスのID | イベントに反応して、例えば新規ビジネスの作成後にそれを取得するために使用できます。 |
販売パートナー識別子 | パートナーアカウントの識別子 | イベントに反応して、例えば、オブジェクトがどのアカウントで作成されたかを識別するために使用できます(複数のアカウントを管理している場合) |
その他のフィールドはイベント タイプごとに異なり、後ほど説明します。
サイン
署名は、イベントフィールドを文字列にキャストし、販売パートナーの秘密鍵を使用してHMAC_SHA256で暗号化し、その結果をBASE64でエンコードすることで計算されます。デコードする前に、イベントフィールドをアルファベット順に並べる必要があります。
疑似コード:
let json = {"asd": "qwe", "foo": "bar"};
str を json.encodeAsJson() とします。
アサート str === '{"asd": "qwe", "foo": "bar"}';
privateKey = "これは秘密鍵です"
暗号化 = hmacShaEncrypt(秘密鍵, str)
署名をencrypted.encodeAsBase64()とする
アサート署名 === 'UAQuAderRxKW8nMPhyU8oVhS6U8PgG8d/I03lcbNAG4='
イベント
以下はサポートされているイベントのリストです。
リスト同期チェック
リスティングの3つの主要なステータス(申請、フロー、同期)のいずれかが変更されたことを示します。リスティングのライフサイクルとGoogleのステータスに関する情報が含まれます。
{
"signature": "X",
"event": {
"claimStatusChanged": false,
"directoriesPublishingStatus": VERIFIED,
"directoriesPublishingStatusChanged": true,
"directoryConnectStatus": CONNECTED,
"directoryType": "GOOGLE",
"flowStatusChanged": true,
"fromListingClaimStatus": "CLAIMED_BY_US",
"fromListingFlowStatus": "ALL_INFORMATION_SUBMITTED",
"fromListingSyncStatus": "NOT_IN_SYNC",
"id": 213581003,
"listing": 332874,
"location": 34838,
"syncStatusChanged": true,
"time": "2016-05-03T10:42:06.000+02:00",
"toListingClaimStatus": "CLAIMED_BY_US",
"toListingFlowStatus": "NO_ACTION_NEEDED",
"toListingSyncStatus": "IN_SYNC",
"type": "LISTING_SYNC_CHECK"
}
}
分野 |
タイプ |
説明 |
ディレクトリタイプ | 弦 | このリストが属するディレクトリ |
クレームステータスが変更されました | ブール値 | リスティングのクレームステータスが変更されたかどうかを示す |
ディレクトリ公開ステータス | 弦 | 現在の Google 公開状態(Google のみ)。状態は、VERIFIED、UNVERIFIED、DISABLED、SUSPENDED、DUPLICATE、NEEDS_REVERIFICATION、PENDING_VERIFICATION のいずれかになります。 |
ディレクトリの公開ステータスが変更されました | ブール値 | リスティングの Google 接続ステータスが変更されたかどうかを示します (Google のみに適用) |
ディレクトリ接続ステータス | 接続ステータス | 現在の接続状態 |
フローステータスが変更されました | ブール値 | リスティングのフローステータスが変更されたかどうかを示す |
同期ステータスが変更されました | ブール値 | リスティングの同期ステータスが変更されたかどうかを示す |
リスト請求ステータスから | リスト請求ステータス | 以前のClaimStatus |
fromListingFlowStatus | フローステータス | 以前のFlowStatus |
リスト同期ステータスから | 同期ステータス | 以前のSyncStatus |
リスト請求ステータス | リスト請求ステータス | 新しいClaimStatus |
リストフローステータス | フローステータス | 新しいFlowStatus |
リスト同期ステータス | 同期ステータス | 新しいSyncStatus |
リストステータスの変更
リスティングのステータスが手動で変更されたことを示します。これはリスティングがアクティブ化された際に一度発生し、その後はほとんど発生しません。その後の変更は通常、オペレーションチームまたはエンジニアリングチームによる手動チェックの結果です。
{
"signature": "X",
"event": {
"claimStatusChanged": false,
"directoryType": "ABCLOCAL",
"flowStatusChanged": true,
"fromListingClaimStatus": "CLAIMED_BY_US",
"fromListingFlowStatus": "NO_ACTION_NEEDED",
"fromListingSyncStatus": "NOT_IN_SYNC",
"id": 213581003,
"listing": 332874,
"location": 34838,
"syncStatusChanged": false,
"time": "2016-05-03T10:42:06.000+02:00",
"toListingClaimStatus": "CLAIMED_BY_US",
"toListingFlowStatus": "SUBMISSION_NEEDED",
"toListingSyncStatus": "NOT_IN_SYNC",
"type": "LISTING_STATUS_CHANGE",
"user": "user@example.com"
}
}
分野 | タイプ | 説明 |
ディレクトリタイプ |
弦 |
このリストが属するディレクトリ |
クレームステータスが変更されました |
ブール値 |
請求ステータスが変更されたかどうかを示す |
フローステータスが変更されました |
ブール値 |
フローステータスが変化したかどうかを示す |
同期ステータスが変更されました |
ブール値 |
同期ステータスが変更されたかどうかを示す |
リスト請求ステータスから |
以前のClaimStatus |
|
fromListingFlowStatus |
フローステータス |
以前のFlowStatus |
リスト同期ステータスから |
以前のSyncStatus |
|
リスト請求ステータス |
新しいClaimStatus |
|
リストフローステータス |
フローステータス |
新しいFlowStatus |
リスト同期ステータス |
新しいSyncStatus |
|
ユーザー |
弦 |
ステータスを変更したユーザー |
リストリンクの変更
プラットフォームのリストが別のディレクトリのリストを参照するようになりました。これは手動で行う場合もあれば、ディレクトリ側で以前リンクされていたものよりも適切なリストを検出することで自動的に行う場合もあります。
{
"event": {
"business": 1234,
"comment": "Listing link changed",
"fromListingId": "456",
"fromListingUrl": "http://old-listing.url/456",
"id": 5549734563,
"listing": 2345,
"location": 3456,
"time": "2019-11-18T14:12:36.000+01:00",
"toListingId": "789",
"toListingUrl": "http://new-listing.url/789",
"type": "LISTING_LINK_CHANGE"
},
"signature": "X"
}
分野 |
タイプ |
説明 |
fromListingUrl | 弦 | 古いリストのURL |
リストIDから | 弦 | リスティングの古い外部ID |
リストへのURL | 弦 | 新しいリストのURL |
リストID | 弦 | リスティングの新しい外部ID |
リストデータポイントチェック
リストデータポイント(レビューや写真などの顧客からのフィードバック)のチェック中に、新しいデータポイントが見つかったことを示します。
{
"event": {
"business": 1420951,
"directoryType": "JUDYS_BOOK"
"id": 213580990,
"listing": 332874,
"location": 34838,
"newCheckinsFound": 1,
"newCommentsFound": 1,
"newConversationsFound": 1,
"newDatapointsFound": true,
"newPhotosFound": 1,
"newQuestionsFound": 1,
"newReviewsFound": 1,
"newDataPointIds": [
250976288,
250976289
],
"time": "2016-05-03T10:19:14.000+02:00",
"type": "LISTING_DATAPOINT_CHECK"
},
"signature": "X"
}
分野 |
タイプ |
説明 |
ディレクトリタイプ | 弦 | このリストが属するディレクトリ |
新しい写真が見つかりました |
整数 |
見つかった新しい写真の数 |
新しいレビューが見つかりました |
整数 |
見つかった新しいレビューの数 |
新しいチェックインが見つかりました |
整数 |
見つかった新しいチェックインの数 |
新しい会話が見つかりました |
整数 |
見つかった新しい会話の数 |
新しいコメントが見つかりました |
整数 |
見つかった新しいコメントの数 |
新しい質問が見つかりました |
整数 |
見つかった新しい質問の数 |
新しいデータポイントが見つかりました | ブール値 | 新しいデータポイントが見つかったかどうかを示します |
新しいデータポイントID | 配列 | 新しく見つかったデータポイントのIDが含まれます |
更新されたデータポイントID | 配列 | 既存および変更されたデータポイントの ID が含まれます (例: 顧客レビュー) |
リストデータポイントが無効です
リスティングのデータポイントがディレクトリ上で削除または無効化されたため、こちら側で無効化します。お客様側でも削除または無効化できます。ディレクトリ側でデータポイントが復元される可能性は低いです。
{
"event": {
"business": 1107630,
"deletedDataPointIds": [],
"directoryType": "YELP_API",
"id": "99",
"invalidDataPointIds": [
434424555
],
"listing": 119934719,
"location": 4154762,
"time": "2023-12-20T19:00:34.508+01:00",
"type": "LISTING_DATAPOINT_INVALID"
},
"signature": "YIfeSTln/p2JaPTY3WhVSsFRvy3NgtRhCFzGI/Fc+60="
}
分野 |
タイプ |
説明 |
削除されたデータポイントID | 配列 | 無効化されたデータポイントの返信のID(例:顧客レビューへの所有者の返信) |
無効なデータポイントID | 配列 | 無効化されたデータポイントのID(例:顧客レビュー) |
ディレクトリ_ビジネス_ページ_データ_ポイント_チェック
新しいブランドデータポイントが見つかったことを示します(例:Facebookブランドページのレビュー)
{
"event": {
"business": 244397,
"directoryBusinessPage": 1220,
"directoryType": "FACEBOOK",
"id": 4,
"newDataPointIds": [
289,
299
],
"newDatapointsFound": true,
"time": "2023-12-21T12:03:31.358+01:00",
"type": "DIRECTORY_BUSINESS_PAGE_DATA_POINT_CHECK",
"updatedDataPointIds": [
79,
253
]
},
"signature": "9kTmfuFg9T5LDD59ZodiyOFtoLSItG737ZRL2fBD7O4="
}
分野 |
タイプ |
説明 |
ディレクトリビジネスページ | 整数 | ブランドデータポイントに関連付けられたビジネスページのID |
新しいデータポイントID | 配列 | 新たに発見されたブランドデータポイントのID |
更新されたデータポイントID | 配列 | 既存および変更されたデータポイントの ID が含まれます (例: 顧客レビュー) |
ディレクトリ_ビジネス_ページ_データ_ポイント_無効
ブランドのデータポイントがディレクトリ上で削除または無効化されたため、当社側で無効化します。お客様側でも削除または無効化できます。ディレクトリ側でデータポイントが復元される可能性は低いです。
{
"event": {
"business": 909288,
"deletedDataPointIds": [],
"directoryBusinessPage": 173,
"directoryType": "FACEBOOK",
"id": 7,
"invalidDataPointIds": [
4737279
],
"time": "2024-01-02T17:17:49.664+01:00",
"type": "DIRECTORY_BUSINESS_PAGE_DATA_POINT_INVALID"
},
"signature": "/GHkwuBIxYadsaWPq1V8vztXVuSlf1txDSxZuBAH1UQ="
}
分野 |
タイプ |
説明 |
ディレクトリビジネスページ | 整数 | ブランドデータポイントに関連付けられたビジネスページのID |
削除されたデータポイントID | 配列 | 無効化されたデータポイントの返信のID(例:顧客レビューへの所有者の返信) |
無効なデータポイントID | 配列 | 無効化されたデータポイントのID(例:顧客レビュー) |
リストの更新
リストをディレクトリに送信しようとしたことを示します。
{
"event": {
"business": 7141,
"directoryType": "BING",
"id": 17518447719,
"listing": 7198166,
"location": 450978,
"messages": [
"Listing was updated successfully!"
],
"time": "2021-10-27T16:21:14.000+02:00",
"type": "LISTING_UPDATE",
"updateResult": "SUCCESS",
"updateStatus": null
},
"signature": "X"
}
分野 |
タイプ |
説明 |
ディレクトリタイプ | 弦 | 送信しようとしたディレクトリのリストタイプ |
更新結果 |
弦 |
|
更新ステータス | 弦 |
updateResult = SUCCESS の場合は null。それ以外の場合は次のいずれかになります。
|
場所_作成
アカウントに新しい場所が作成されたことを示します。
{
"event": {
"comment": "A new Location has been created",
"id": 2926113683,
"location": 636605,
"time": "2018-11-05T17:35:07.000+01:00",
"type": "LOCATION_CREATED",
"source": "API"
},
"signature": "X"
}
分野 |
タイプ |
説明 |
ソース |
弦 |
[API、CHECKOUT、CSV_UPLOAD、DEMO_JOB、LOCATION_DATA_DOWNLOAD] のいずれか |
場所ステータスが変更されました
場所のステータスが変更されたことを示します。
{
"event": {
"comment": "Checked and activated by a human being.",
"from": "ACTIVE",
"id": 213580999,
"location": 34838,
"time": "2016-05-03T10:34:43.000+02:00",
"to": "CANCELLED",
"type": "LOCATION_STATUS_CHANGED",
"user": "user@example.com"
},
"signature": "X"
}
ロケーションプロファイルが変更されました
ユーザーが場所のデータを変更したことを示します。
{
"event": {
"comment": "Location profile has been updated",
"id": 2926113683,
"location": 636605,
"time": "2018-11-05T17:35:07.000+01:00",
"type": "LOCATION_PROFILE_CHANGED",
"user": "user@example.com"
},
"signature": "X"
}
分野 |
タイプ |
説明 |
ユーザー | 弦 | データを変更したユーザー |
ビジネス製品計画の変更
ユーザーとAPIの更新、またはシステムによってビジネスの製品プランと割り当てられた場所が変更されたことを示します。
{
"event": {
"business": 1,
"comment": "Business product plan has been changed",
"id": 5136210330,
"salesPartnerIdentifier": "identifier",
"newProductPlanId": 2,
"newProductPlanName": "My Product Plan 2",
"newProductPlanPrice": 20,
"oldProductPlanId": 1,
"oldProductPlanName": "My Product Plan 1",
"oldProductPlanPrice": 10,
"time": "2019-10-09T15:10:01.000+02:00",
"type": "BUSINESS_PRODUCT_PLAN_CHANGED",
"changedBy": "user@example.com"
},
"signature": "XYZ"
}
分野 |
タイプ |
説明 |
新しい製品プランID | 長さ | 新しく割り当てられた製品プランのID |
新しい製品プラン名 | 弦 | 新しく割り当てられた製品プランの名前 |
新製品プラン価格 | 整数 | 新しく割り当てられた製品プランの価格(セント) |
古い製品プランID | 長さ | 以前に割り当てられたProductPlanのID |
旧製品プラン名 | 弦 | 以前に割り当てられた製品プランの名前 |
旧製品プラン価格 | 整数 | 以前に割り当てられた製品プランの価格(セント) |
変更者 | 弦 | 変更をトリガーした人物を示す次のいずれか: 1. ユーザーのメールアドレス 2. 「プライベートトークン」 3. 「システム」 |
ビジネス作成
パートナーアカウントに新しいビジネスが作成されたことを示します
{
"event": {
"business": 631498,
"changedBy": "PRIVATE_TOKEN",
"comment": "New business has been created",
"id": 5385813249,
"salesPartnerIdentifier": "identifier",
"time": "2019-11-07T16:30:19.000+01:00",
"type": "BUSINESS_CREATED"
},
"signature": "X”
}
分野 |
タイプ |
説明 |
変更者 | 弦 | 変更をトリガーした人物を示す次のいずれか: 1. ユーザーのメールアドレス 2. 「プライベートトークン」 3. 「システム」 |