Webhook

連携機能がインストールされている場合、Webhook APIを使用して、HubSpotアカウント上で発生したイベントを受信できます。接続されたアカウントでイベントが発生したときにAPI呼び出しを実行する代わりに、設定したエンドポイントにHubSpotからHTTPリクエストを送信します。受信を登録するイベントは、アプリの設定、または以下で詳述するエンドポイントを使用して設定できます。場合によっては、定期的に変更をポーリングするよりも、Webhookを使用する方法のほうが拡張性に優れています（特にインストールベースが大規模なアプリの場合）。

Webhook APIの使用にあたり、次の要件を満たす必要があります。

• 通知を受ける対象のイベントに登録し、通知の送信先URLを指定することにより、Webhookを使用するHubSpotアプリを設定してあること。アプリの作成方法の詳細については、前提条件に関するドキュメント（英語）をご覧ください。
• このドキュメントに規定されたWebhookペイロードを処理できる、公開URLのセキュア（HTTPS）エンドポイントが展開されていること。

Webhookは、アカウント単位ではなくHubSpotアプリ（英語）に対して設定されます。OAuthフロー（英語）に従ってアプリをインストールする全てのアカウントが、そのフローのWebhookサブスクリプションに配信登録されます。

CRMオブジェクト（コンタクト、会社、取引、チケット、製品、商品項目など）のイベントとコミュニケーションイベントに対して配信登録できます。

Webhookを使用してCRMイベントの配信登録を行うには、crm.objects.contacts.readスコープを求めるようにアプリを設定する必要があります。また、コミュニケーションイベントの配信登録を行うには、conversations.readスコープを求めるようにアプリを構成する必要があります。

Webhookサブスクリプションを作成するには、その前に、これらのスコープを設定する必要があります。スコープの詳細（英語）およびアプリの認証認証URLの設定（英語）については、OAuthのドキュメントをご覧ください。

アプリが既にWebhookを使用している場合、アプリから全てのWebhookサブスクリプションを削除するまでは、crm.objects.contacts.readスコープまたはconversations.readスコープを削除できません。

Webhookサブスクリプションを設定する前に、これらの通知の送信先URLを指定する必要があります。また、イベントスロットリング制限も調整できます。これは、エンドポイントで処理できる同時リクエスト数の上限です。

スロットル制限は同時処理の制限であるため、リクエストに対するレスポンスが返されると同時にアクティブなリクエストの合計数が1つ減り、別のリクエストを送信できるようになります。例えば、10秒あたり1リクエストという制限を設けている場合、HubSpotが1つのリクエストを送信してから次のリクエストを送信するのは、レスポンスを受け取った時点、または別のリクエストが送信されてから10秒経過した時点のどちらかの内の早い方となります。

このレート制限の設定は、HubSpotがAPIに過大な負荷をかけずに通知をできるだけ早く送信するために役立ちます。

• この制限を低く設定しすぎると、APIに送信される通知の数が多い場合は上限数に達した状態が数秒以上続いて、通知の送信がタイムアウトする可能性があります。その場合、通知に遅延が発生します。 
• 制限が高すぎると、エンドポイントで利用可能なリソースが飽和状態になり、レスポンスの低速化、通知の遅延、またはエンドポイントの応答不可といった問題が発生することがあります。

 開発者アカウントのアプリの設定ページでは、URLとスロットリング制限を管理できます。

• 開発者アカウントで、［アプリ］ダッシュボードに移動します。
• Webhookを設定する対象のアプリの名前をクリックします。 
  
• 左のサイドバーメニューで［Webhook］に移動します。
• ［ターゲットURL］フィールドに、イベントがトリガーされたときにHubSpotでPOSTリクエストを送信する宛先のURLを入力します。
• ［イベントの抑制］設定を使用して、HubSpotで送信を試みるイベントの最大数を調整します。 

• ［保存］をクリックします。 

以下のエンドポイントと開発者APIキーを使用することで、アプリのWebhook設定をプログラムによって構成できます。

アプリに現在構成されているWebhookの設定を表示するには、GETリクエストをwebhooks/v3/{appId}/settingsに送信します。

リクエストにはアプリID（英語）を含める必要があります。アプリIDは、［アプリ］ダッシュボード内のアプリの名前の下、またはアプリの設定の［認証］タブで確認できます。

settingsオブジェクトは、以下のフィールドからなります。

上記の設定を編集するには、PUTリクエストをwebhooks/v3/{appId}/settingsに送信します。このリクエスト本文には、以下のフィールドを含めます。

以下に、リクエストの例を示します。

Webhook URLとイベントスロットリングを設定したら、1つ以上のサブスクリプションを作成する必要があります。WebhookサブスクリプションでHubSpotに対し、特定のアプリで受信するイベントを指示します。

サブスクリプションは、貴社の連携機能をインストールした全ての顧客に適用されます。つまり、必要なサブスクリプションを指定するのは一度だけでよいことになります。アプリケーションでサブスクリプションを有効にすると、そのアプリケーションをインストールした全ての顧客のWebhookの受信が自動的に開始されます。また、連携機能によって新しい顧客からのWebhookトリガーの受信も開始されます。

サポートされているサブスクリプションタイプは次のとおりです。API経由でサブスクリプションを作成する際に、これらのタイプをeventTypeフィールドの値として使用できます。

現在ベータ版となっているコミュニケーション受信トレイおよびメッセージAPIを使用している場合は、以下のコミュニケーション サブスクリプション タイプの配信登録を行うことができます。 

プロパティー変更サブスクリプションの場合、通知の対象とするプロパティーを指定する必要があります。複数のプロパティー変更サブスクリプションを指定できます。サブスクリプションで指定されているプロパティーが顧客のアカウントに存在しない場合、顧客からそのプロパティーに関するWebhookを受け取ることはありません。

一部のプロパティーは、CRMプロパティー変更サブスクリプションでは使用できません。該当するプロパティーは次の通りです。

• num_unique_conversion_events
• hs_lastmodifieddate

現在ベータ版となっているコミュニケーション受信トレイおよびメッセージAPIを使用している場合、以下のプロパティーを使用できます。

• assignedTo：スレッドが再割り当てまたは割り当て解除されたコミュニケーション。propertyValueは、スレッドが再割り当てされた場合はWebhookのペイロードに含まれるアクターIDとなり、スレッドが割り当て解除された場合は空白となります。
• status：スレッドによって変更されたコミュニケーションのステータス。Webhookペイロード内のpropertyValueは、OPENまたはCLOSEDのいずれかになります。
• isArchived：スレッドが復元されたコミュニケーション。Webhookペイロード内のpropertyValueは、常にFALSEとなります。 

HubSpot開発者アカウント内でWebhookサブスクリプションを作成できます。 

• HubSpotの開発者アカウントで、［アプリ］ダッシュボードに移動します。 
• アプリの名前をクリックします。 
• 左のサイドバーメニューで［Webhook］に移動します。 
• ［サブスクリプションを作成］をクリックします。 
• 右側のパネルで［どのオブジェクトタイプを選びますか？］のドロップダウンメニューをクリックし、サブスクリプションを作成する対象のオブジェクトを選択します。 
• ［どのイベントについて知りたいですか？］のドロップダウンメニューをクリックし、イベントタイプを選択します。 

• プロパティー変更イベントのサブスクリプションを作成する場合は、［どのプロパティーを選びますか？］のドロップダウンメニューをクリックし、対象とするプロパティーを選択します。 
  
• ［配信登録］をクリックします。 

Webhook設定にサブスクリプションが表示されます。新しいサブスクリプションは一時停止状態で作成されるため、Webhookが送信されるようにするためにはサブスクリプションを有効にする必要があります。

• ［イベントのサブスクリプション］セクションで、オブジェクトタイプにカーソルを合わせ、［サブスクリプションを表示］をクリックします。 
• イベントの横にあるチェックボックスをオンにしてから、テーブルのヘッダーで［アクティベート］をクリックします。 

以下のエンドポイントを使用すれば、プログラムに従ってサブスクリプションを作成できます。これらのエンドポイントにリクエストを送信する際は、開発者APIキーを使用する必要があります。 

subscriptionオブジェクトには、以下のフィールドを格納できます。

サブスクリプションのリストを取得するには、GETリクエストをwebhooks/v3/{appId}/subscriptionsに送信します。

レスポンスとして、サブスクリプションを表すオブジェクトの配列が返されます。各オブジェクトには、サブスクリプションに関する情報（ID、作成日、タイプ、現在有効になっているかどうかなど）が格納されています。レスポンスの例を次に示します。

新しいサブスクリプションを作成するには、POSTリクエストをwebhooks/v3/{appId}/subscriptionsに送信します。

リクエスト本文には、以下のフィールドを含めることができます。

id、createdAt、createdByの各フィールドは自動的に設定されるため、リクエスト本文に含める必要はありません。

以下のリクエスト本文の例をご参照ください。 

eventTypeには、前のセクションで定義されている有効なサブスクリプションタイプを指定する必要があります。また、propertyNameは有効なプロパティー名でなければなりません。顧客がこの値に一致するプロパティーを定義していない場合、このサブスクリプションによる通知は行われません。

リクエスト本文には、以下のフィールドを含めます。

サブスクリプションを削除するには、DELETEリクエストをwebhooks/v3/{appId}/subscriptions/{subscriptionId}に送信します。

アプリのWebhook設定で指定したターゲットURLにあるエンドポイントでは、HubSpotから送信される、JSON形式のデータを含むPOSTリクエストを受信します。

Webhookエンドポイントで取得しているリクエストが実際にHubSpotから送信されたものであることを保証するために、HubSpotは、X-HubSpot-Signatureヘッダーを、貴社のアプリのクライアントシークレットとリクエスト詳細の組み合わせに基づくSHA-256ハッシュにします。詳しくはリクエスト署名の検証方法をご覧ください。

以下の表を使用して、ペイロードに含まれる可能性のあるフィールドの詳細を確認してください。

上に示されているように、単一のリクエストによって複数のオブジェクトからなる配列が返されるはずです。一括処理のサイズはさまざまですが、通知は100件未満になります。短時間に多数のイベントが発生した場合に、HubSpotは複数の通知を送信します。例えば、新しいコンタクトの受信を登録している状態で、顧客が多数のコンタクトをインポートした場合、HubSpotはリクエストに対して1つではなく、一括でインポートされたコンタクトに対して複数の通知を送信します。

HubSpotは、ユーザーがこれらの通知をイベントの発生順に受信することを保証できません。イベントが通知の発生をトリガーしたタイミングを判定するには、各通知のoccurredAtプロパティーを使用してください。

また、HubSpotはイベントあたり1件の通知のみを受信することを保証できません。非常にまれですが、HubSpotが同じ通知を複数回送信する場合があります。

HubSpotユーザーは、プライバシーに関する法律に準拠するためにコンタクトレコードを完全に削除することができます。詳細は、GDPRに準拠した削除に関するナレッジベース記事をご覧ください。

contact.privacyDeletion配信カテゴリー(サブスクリプションタイプ)の配信登録を行うことにより、ユーザーがプライバシーに準拠するためにコンタクトを削除した時点で、Webhook通知を受信できます。

プライバシー削除通知には特別な動作があります。

• プライバシー削除イベントによってコンタクト削除イベントもトリガーされるため、両方のイベントの受信を登録している場合は2つの通知を受け取ります。
• これらの通知は、必ずしも特定の順序で送信されたり、同じ一括配信で送信されたりするわけではありません。個別のメッセージとの照合にはオブジェクトIDを使用する必要があります。

Webhookのエンドポイントで取得しているリクエストが実際にHubSpotから送信されたことを保証するために、HubSpotはX-HubSpot-Signatureヘッダーに、アプリのクライアントシークレットと、HubSpotが送信するリクエスト本文を連結して作成したSHA-256ハッシュを取り込みます。

この署名を検証するには、アプリケーションのアプリシークレットと、処理中のリクエストに含まれる未解析のリクエスト本文を連結して生成されたSHA-256ハッシュを取得します。生成されたハッシュとX-HubSpot-Signatureの値を比較します。これらの値が一致する場合、リクエストはHubSpotから送信されたことが検証されます。一致しない場合、アプリシークレットを知っている他のユーザーからリクエストが送信されたことになります。従って、この値の機密保持には十分ご注意ください。

これらの値が一致しない場合、転送中のリクエストの改ざん、またはエンドポイントに対してWebhook通知を用いたなりすましが発生した恐れがあります。

署名の検証について詳細を確認してください。 

貴社のサービスで通知処理に問題が発生した場合、常に、HubSpotから失敗した通知の再送信が最大10回試行されます。

HubSpotが再試行する場合は次のとおりです。

• 接続失敗：指定されたWebhook URLへのHTTP接続をHubSpotが開始できない場合。 
• タイムアウト：貴社のサービスから一括の通知に対するレスポンスの返送に5秒を超える時間がかかった場合 
• エラーコード：貴社のサービスがHTTPステータスコード（4xxまたは5xx）でレスポンスした場合

通知の送信は最大で10回再試行されます。再試行は、24時間にわたりリクエストの送信間隔を変えながら実行されます。失敗が同時に多発した場合の再試行時刻が完全に同じにならないように、個々の通知にある程度のばらつきが確保されます。

1つのアプリあたり最大1,000件のサブスクリプションを作成できます。この制限を超えて作成しようとすると、以下の本文を含む400 bad requestが返されます。