Webhook APIを使用するには次の要件があります。
- 通知を受けるイベントの受信を登録し、通知の送信先URLを指定することにより、Webhookを使用するHubSpotアプリを設定してあること。アプリの作成の詳細については、前提条件ドキュメント（英語）をご覧ください。
- このドキュメントに規定されたWebhookペイロードを処理できる、公開URLのセキュア（HTTPS）エンドポイントが展開されていること。
Webhookは、アカウント単位ではなくHubSpotアプリ（英語）用としてセットアップされます。（OAuthフロー（英語）に従って）アプリをインストールするアカウントがWebhookサブスクリプションに登録されます。
スコープ
Webhookを使用するには、contactsスコープを求めるようにアプリを設定する必要があります。このスコープはWebhookサブスクリプションを作成する前にセットアップする必要があり、アプリ設定の開発者アカウントから、またはWebhook APIを使用してサブスクリプションを設定するときに設定します。スコープの詳細およびアプリの認証URLの設定については、OAuthのドキュメント（英語）を参照してください。
アプリがすでにWebhookを使用している場合、アプリから全てのWebhookサブスクリプションを削除するまで、contactsスコープを削除できなくなります。
Webhookのセットアップ
注：Webhook設定は最大5分までキャッシュできます。Webhook URL、レート制限、またはサブスクリプション設定を変更すると、変更が有効になるまでに最大5分かかる場合があります。
Webhook URLとレート制限
Webhookサブスクリプションを設定する前に、これらの通知の送信先URLを指定する必要があります。また、エンドポイントがリクエストを処理できるようにレートを調整することもできます。
このレート制限を設定すると、APIに過大な負荷をかけずに通知をできるだけ早く送信するために役立ちます。
- 制限が低すぎると、APIに送信された通知が多すぎた場合にこの制限が数秒間飽和状態になり、通知がタイムアウトすることがあります。その結果、通知を受け取るまでに遅延が発生します。
- 制限が高すぎると、エンドポイントで利用可能なリソースが飽和状態になり、レスポンスの低速化、通知の遅延、またはエンドポイントの応答不可といった問題が発生することがあります。
UIでの管理
開発者アカウント上のアプリの設定ページで、URLとレート制限設定を管理できます。
1. アプリダッシュボードでWebhookをセットアップするアプリを選択します。
2. 左側のナビゲーション項目で［Webhook］を選択します。この画面に、ターゲットURLとイベントスロットリング制限を設定するインターフェイスが表示されます。
API経由の管理
これらのエンドポイントを使用すると、プログラムによってアプリのWebhookを設定することが可能です。アプリをセットアップする際にはUIを使用することをお勧めします。これらのエンドポイントへのリクエストを行うときには、開発者APIキーを使用する必要があります。
設定フィールド
設定オブジェクトには次のフィールドがあります。
webhookUrl- Webhook通知の送信先URL。HTTPS経由で提供する必要があります。maxConcurrentRequests- このURLの同時接続制限は「Webhook URLと同時接続制限」で説明します。
設定の表示
貴社のアプリ用に現在セットアップされたWebhook設定がある場合は次のエンドポイントでアクセスします。
GET https://api.hubapi.com/webhooks/v3/{appId}/settings
結果は次のようになります。
{
"webhookUrl": "https://testing.com/webhook",
"maxConcurrentRequests":20
}
設定の更新
これらの設定を変更するには、次のエンドポイントを使用できます。
PUT https://api.hubapi.com/webhooks/v3/{appId}/settings
リクエスト本文は次のようになります。
{
"webhookUrl": "https://testing.com/webhook-modified",
"maxConcurrentRequests":25
}検証：
webhookUrlはHTTPS経由で提供される有効なURLである必要があります。maxConcurrentRequestsは5より大きい数字でなければなりません。
Webhookサブスクリプション
Webhook URlとレート制限設定をセットアップしたら、1つ以上のサブスクリプションを作成する必要があります。Webhookサブスクリプションは、特定のアプリが受信するイベントをHubSpotに伝える仕組みです。現在、次のタイプのサブスクリプションをサポートしています。
- コンタクトの作成
- コンタクトの削除
- プライバシー規則に準拠したコンタクト削除 - 詳細はこちら（英語）を参照してください。
- コンタクトのプロパティーの変更
- 会社の作成
- 会社の削除
- 会社のプロパティーの変更
- 取引の作成
- 取引の削除
- 取引のプロパティーの変更
サブスクリプションについては、以下の点にご注意ください。
プロパティー変更サブスクリプションの場合、通知するプロパティーを指定する必要があります。複数のプロパティー変更サブスクリプションを指定できます。サブスクリプションで指定されたプロパティーが顧客のアカウント上にない場合、この顧客からはそのプロパティーのWebhookを取得できません。
一部のプロパティーは、プロパティー変更サブスクリプションでは使用できません。該当するプロパティーは次のとおりです。
コンタクトのプロパティー：
num_unique_conversion_eventshs_lastmodifieddate
サブスクリプションは、貴社の連携機能をインストールした全ての顧客に適用されます。つまり、必要なサブスクリプションを指定するのは一度だけでよいことになります。アプリのサブスクリプションを有効にすると、貴社のアプリをインストールした全ての顧客のWebhookが自動的に開始され、連携機能をインストールした新しい顧客からのWebhookの取得は自動的に開始されます。
サブスクリプションの作成または変更を行ってから変更が有効になるまでに、最大5分の遅延が生じる場合があります。
UIでのサブスクリプション管理
Webhookサブスクリプションは、開発者アカウント上で作成できます。
- 開発者アプリダッシュボードで、Webhookを送信するアプリを選択します。
- ［Webhookサブスクリプション］ナビゲーション項目を選択します。
- ［サブスクリプションを作成］をクリックします。
- オブジェクトタイプ（例：コンタクト、会社、取引）とイベントタイプ（例：作成、変更、削除）を選択します。 注：プライバシーのための削除は、選択されたオブジェクトタイプが「コンタクト」のみである場合にのみ選択できます。
- （任意）プロパティー変更イベントの場合、対象のプロパティーを選択します。注：プロパティー名を手動で入力することもできるので、カスタムプロパティーを使用できます。
注：新しいサブスクリプションは一時停止状態で作成されます。送信には、Webhookのサブスクリプションを有効化する必要があります。
API経由のサブスクリプション管理
これらのエンドポイントを使用すると、プログラムによってサブスクリプションを作成することが可能です。UIでできることとエンドポイントでできることの間に違いはないため、アプリの設定にはUIを使用することをお勧めします。これらのエンドポイントへのリクエストを行うときには、開発者APIキーを使用する必要があります。
サブスクリプションフィールド
サブスクリプションオブジェクトには次のフィールドがあります。
id- サブスクリプションごとのIDを表す数値。createdAt- このサブスクリプションが作成された時点のミリ秒単位のタイムスタンプ。createdBy- このサブスクリプションを作成したユーザーのユーザーID。enabled- このサブスクリプションが現在有効で通知のトリガーが行われるかどうか。subscriptionDetails- このサブスクリプションによってリスニングされるイベントのタイプを表します。subscriptionType- 下記の「サブスクリプションタイプ」で定義されたサブスクリプションタイプを表す文字列。propertyName-プロパティーの変更にのみ必要。変更のリスニング対象となるプロパティーの名前。単一のプロパティー名のみ指定可能です。
サブスクリプションタイプ
subscriptionTypeプロパティーは次のいずれかの値になります。
contact.creation- 顧客のアカウントでコンタクトが作成された場合に通知を受け取る。contact.deletion- 顧客のアカウントでコンタクトが削除された場合に通知を受け取る。contact.privacyDeletion- プライバシー規則への順守を理由としてコンタクトが削除された場合に通知を受け取る。 詳細はこちら（英語）を参照してください。contact.propertyChange- 顧客のアカウント上の全てのコンタクトについて、指定したプロパティーが変更された場合に通知を受け取る。company.creation- 顧客のアカウント上で会社が作成された場合に通知を受け取る。company.deletion- 顧客のアカウント上で会社が削除された場合に通知を受け取る。company.propertyChange- 顧客のアカウントの全ての会社について、指定したプロパティーが変更された場合に通知を受け取る。deal.creation- 顧客のアカウント上で取引が作成された場合に通知を受け取る。deal.deletion- 顧客のアカウント上で取引が削除された場合に通知を受け取るdeal.propertyChange-顧客のアカウント上の全ての取引について、指定したプロパティーが変更された場合に通知を受け取る。
サブスクリプションの取得
サブスクリプションのリストは次のように取得します。
GET https://api.hubapi.com/webhooks/v3/{appId}/subscriptions
レスポンスはサブスクリプションを表すオブジェクトの配列です。各オブジェクトには、ID、作成日、タイプ、現在有効になっているかどうかなどのサブスクリプションに関する情報が含まれます。レスポンスの例を次に示します。