Webhook
連携機能がインストールされている場合、Webhook APIを使用して、HubSpotアカウント上で発生したイベントを受信できます。接続されたアカウントでイベントが発生したときにAPI呼び出しを実行する代わりに、設定したエンドポイントにHubSpotからHTTPリクエストを送信します。受信を登録するイベントは、アプリの設定、または以下で詳述するエンドポイントを使用して設定できます。場合によっては、定期的に変更をポーリングするよりも、Webhookを使用する方法のほうが拡張性に優れています（特にインストールベースが大規模なアプリの場合）。
Webhook APIの使用にあたり、次の要件を満たす必要があります。
- 通知を受ける対象のイベントに登録し、通知の送信先URLを指定することにより、Webhookを使用するHubSpotアプリを設定してあること。アプリの作成方法の詳細については、前提条件に関するドキュメント（英語）をご覧ください。
- このドキュメントに規定されたWebhookペイロードを処理できる、公開URLのセキュア（HTTPS）エンドポイントが展開されていること。
Webhookは、アカウント単位ではなくHubSpotアプリ（英語）に対して設定されます。OAuthフロー（英語）に従ってアプリをインストールする全てのアカウントが、そのフローのWebhookサブスクリプションに配信登録されます。
CRMオブジェクト（コンタクト、会社、取引、チケット、製品、商品項目など）のイベントとコミュニケーションイベントに対して配信登録できます。
注：
- 非公開アプリでWebhookを管理することもできます。非公開アプリでは、非公開アプリのアプリ内設定でのみWebhookを編集できます。現在のところ、APIを介して編集することはできません。
- コミュニケーションWebhookに登録するには、現在ベータ版となっているコミュニケーション受信トレイおよびメッセージAPIにアクセスする必要があります
Webhookを使用してCRMイベントの配信登録を行うには、crm.objects.contacts.readスコープを求めるようにアプリを設定する必要があります。また、コミュニケーションイベントの配信登録を行うには、conversations.readスコープを求めるようにアプリを構成する必要があります。
Webhookサブスクリプションを作成するには、その前に、これらのスコープを設定する必要があります。スコープの詳細（英語）およびアプリの認証認証URLの設定（英語）については、OAuthのドキュメントをご覧ください。
アプリが既にWebhookを使用している場合、アプリから全てのWebhookサブスクリプションを削除するまでは、crm.objects.contacts.readスコープまたはconversations.readスコープを削除できません。
Webhookサブスクリプションを設定する前に、これらの通知の送信先URLを指定する必要があります。アプリのサブスクリプションを完全に設定する方法については、以下のセクションの手順に従ってください。
注：
- Webhook設定は最大5分までキャッシュできます。WebhookのURL、同時接続数上限、またはサブスクリプションの設定を変更すると、変更が適用されるまでに最大5分かかる場合があります。
- HubSpotは、アプリをインストールしたアカウントに関連付けられたサブスクリプション イベント データを送信するときに、10件のリクエストの同時実行制限を設定します。この同時実行制限は、HubSpotが一度に試行する実行中リクエストの最大数です。各リクエストには最大100件のイベントを含めることができます。
開発者アカウントのアプリの設定ページでは、URLとスロットリング制限を管理できます。
- 開発者アカウントで、［アプリ］ダッシュボードに移動します。
- Webhookを設定する対象のアプリの名前をクリックします。
- 左のサイドバーメニューで［Webhook］に移動します。
- ［ターゲットURL］フィールドに、イベントがトリガーされたときにHubSpotでPOSTリクエストを送信する宛先のURLを入力します。
- ［イベントの抑制］設定を使用して、HubSpotで送信を試みるイベントの最大数を調整します。
- ［保存］をクリックします。
| フィールド | Description |
|---|---|
webhookUrl
| HubSpotがWebhook通知を送信する宛先のURL。このURLはHTTPS経由で提供する必要があります。 |
maxConcurrentRequests
| Webhook URLでの同時処理の制限。このフィールドには5より大きい値を設定する必要があります。 |
上記の設定を編集するには、PUTリクエストをwebhooks/v3/{appId}/settingsに送信します。このリクエスト本文には、以下のフィールドを含めます。
| フィールド | Description |
|---|---|
targetUrl
| HubSpotがイベントペイロードを配信するために呼び出す、一般公開されたURL。 |
throttling
| このオブジェクトでWebhookスロットリングの詳細を構成します。throttlingオブジェクト内には |
period
| この設定で使用する時間の単位。 |
maxConcurrentRequests
|
|
以下に、リクエストの例を示します。
Webhook URLとイベントスロットリングを設定したら、1つ以上のサブスクリプションを作成する必要があります。WebhookサブスクリプションでHubSpotに対し、特定のアプリで受信するイベントを指示します。
サブスクリプションは、貴社の連携機能をインストールした全ての顧客に適用されます。つまり、必要なサブスクリプションを指定するのは一度だけでよいことになります。アプリケーションでサブスクリプションを有効にすると、そのアプリケーションをインストールした全ての顧客のWebhookの受信が自動的に開始されます。また、連携機能によって新しい顧客からのWebhookトリガーの受信も開始されます。
サポートされているサブスクリプションタイプは次のとおりです。API経由でサブスクリプションを作成する際に、これらのタイプをeventTypeフィールドの値として使用できます。
| サブスクリプションタイプ | 必要なスコープ | 説明 |
|---|---|---|
contact.creation |
crm.objects.contacts.read |
顧客のアカウントでコンタクトが作成された場合に通知を受け取ります。 |
contact.deletion |
顧客のアカウントからコンタクトが削除された場合に通知を受け取ります。 | |
contact.merge |
コンタクトが別のコンタクトとマージされた場合に通知を受け取ります。 | |
contact.associationChange |
コンタクトと他のサポート対象のWebhookオブジェクト（コンタクト、会社、取引、チケット、商品項目、または製品）との間の関連付けが追加または削除された場合に通知を受け取ります。 | |
contact.restore |
削除されたコンタクトが復元された場合に通知を受け取ります。 | |
contact.privacyDeletion |
プライバシー規則への順守を理由としてコンタクトが削除された場合に通知を受け取ります。 | |
contact.propertyChange |
アカウントの全てのコンタクトについて、指定したプロパティーが変更された場合に通知を受け取ります。 | |
company.creation |
crm.objects.companies.read |
顧客のアカウントで会社レコードが作成された場合に通知を受け取ります。 |
company.deletion |
顧客のアカウントから会社レコードが削除された場合に通知を受け取ります。 | |
company.propertyChange |
顧客のアカウントの全ての会社レコードについて、指定したプロパティーが変更された場合に通知を受け取ります。 | |
company.associationChange |
会社オブジェクトと他のサポート対象のWebhookオブジェクト（コンタクト、会社、取引、チケット、商品項目、または製品）との間の関連付けが追加または削除された場合に通知を受け取ります。 | |
company.restore |
削除された会社レコードが復元された場合に通知を受け取ります。 | |
company.merge |
会社レコードが別の会社レコードとマージされた場合に通知を受け取ります。 | |
deal.creation |
crm.objects.deals.read |
顧客のアカウントで取引レコードが作成された場合に通知を受け取ります。 |
deal.deletion |
顧客のアカウントから取引レコードが削除された場合に通知を受け取ります。 | |
deal.associationChange |
取引と他のサポート対象のWebhookオブジェクト（コンタクト、会社、取引、チケット、商品項目、または製品）との間の関連付けが追加または削除された場合に通知を受け取ります。 | |
deal.restore |
削除された取引レコードが復元された場合に通知を受け取ります。 | |
deal.merge |
取引レコードが別の取引レコードとマージされた場合に通知を受け取ります。 | |
deal.propertyChange |
顧客のアカウント上の全ての取引について、指定したプロパティーが変更された場合に通知を受け取ります。 | |
ticket.creation |
tickets |
顧客のアカウントでチケットが作成された場合に通知を受け取ります。 |
ticket.deletion |
顧客のアカウントからチケットが削除された場合に通知を受け取ります。 | |
ticket.propertyChange |
顧客のアカウント上のチケットのいずれかで、指定したプロパティーが変更された場合に通知を受け取ります。 | |
ticket.associationChange |
チケットと他のサポート対象のWebhookオブジェクト（コンタクト、会社、取引、チケット、商品項目、または製品）との間の関連付けが追加または削除された場合に通知を受け取ります。 | |
ticket.restore |
削除されたチケットが復元された場合に通知を受け取ります。 | |
ticket.merge |
チケットが別のチケットとマージされた場合に通知を受け取ります。 | |
product.creation |
e-commerce |
顧客のアカウント上で製品レコードが作成された場合に通知を受け取ります。 |
product.deletion |
顧客のアカウント上で製品レコードが削除された場合に通知を受け取ります。 | |
product.restore |
削除された製品レコードが復元された場合に通知を受け取ります。 | |
product.merge |
製品が別の製品とマージされた場合に通知を受け取ります。 | |
product.propertyChange |
顧客のアカウント上の製品のいずれかで、指定したプロパティーが変更された場合に通知を受け取ります。 | |
line_item.creation |
顧客のアカウントで商品項目が作成された場合に通知を受け取ります。 | |
line_item.deletion |
顧客のアカウント上で商品項目が削除された場合に通知を受け取ります。 |
|
line_item.associationChange |
商品項目と他のサポート対象のWebhookオブジェクト（コンタクト、会社、取引、チケット、商品項目、または製品）との間の関連付けが追加または削除された場合に通知を受け取ります。 | |
line_item.restore |
削除された商品項目が復元された場合に通知を受け取ります。 | |
line_item.merge |
商品項目が別の商品項目とマージされた場合に通知を受け取ります。 | |
line_item.propertyChange |
顧客のアカウント上の商品項目のいずれかで、指定したプロパティーが変更された場合に通知を受け取ります。 |
現在ベータ版となっているコミュニケーション受信トレイおよびメッセージAPIを使用している場合は、以下のコミュニケーション サブスクリプション タイプの配信登録を行うことができます。
| サブスクリプションタイプ | スコープ | 説明 |
|---|---|---|
conversation.creation |
conversations.read |
アカウントで新しいスレッドが作成された場合に通知を受け取ります。 |
conversation.deletion |
アカウントでスレッドがアーカイブされた場合、またはソフト削除された場合に通知を受け取ります。 | |
conversation.privacyDeletion |
アカウントからスレッドが完全に削除された場合に通知を受け取ります。 | |
conversation.propertyChange |
スレッドのプロパティーが変更された場合に通知を受け取ります。 | |
conversation.newMessage |
スレッドで新しいメッセージを受信した場合に通知を受け取ります。 |
プロパティー変更サブスクリプションの場合、通知の対象とするプロパティーを指定する必要があります。複数のプロパティー変更サブスクリプションを指定できます。サブスクリプションで指定されているプロパティーが顧客のアカウントに存在しない場合、顧客からそのプロパティーに関するWebhookを受け取ることはありません。
一部のプロパティーは、CRMプロパティー変更サブスクリプションでは使用できません。該当するプロパティーは次の通りです。
num_unique_conversion_eventshs_lastmodifieddate
現在ベータ版となっているコミュニケーション受信トレイおよびメッセージAPIを使用している場合、以下のプロパティーを使用できます。
assignedTo：スレッドが再割り当てまたは割り当て解除されたコミュニケーション。propertyValueは、スレッドが再割り当てされた場合はWebhookのペイロードに含まれるアクターIDとなり、スレッドが割り当て解除された場合は空白となります。status：スレッドによって変更されたコミュニケーションのステータス。Webhookペイロード内のpropertyValueは、OPENまたはCLOSEDのいずれかになります。isArchived：スレッドが復元されたコミュニケーション。Webhookペイロード内のpropertyValueは、常にFALSEとなります。
HubSpot開発者アカウント内でWebhookサブスクリプションを作成できます。
- HubSpotの開発者アカウントで、［アプリ］ダッシュボードに移動します。
- アプリの名前をクリックします。
- 左のサイドバーメニューで［Webhook］に移動します。
- ［サブスクリプションを作成］をクリックします。
- 右側のパネルで［どのオブジェクトタイプを選びますか？］のドロップダウンメニューをクリックし、サブスクリプションを作成する対象のオブジェクトを選択します。
- ［どのイベントについて知りたいですか？］のドロップダウンメニューをクリックし、イベントタイプを選択します。
- プロパティー変更イベントのサブスクリプションを作成する場合は、［どのプロパティーを選びますか？］のドロップダウンメニューをクリックし、対象とするプロパティーを選択します。
- ［配信登録］をクリックします。
Webhook設定にサブスクリプションが表示されます。新しいサブスクリプションは一時停止状態で作成されるため、Webhookが送信されるようにするためにはサブスクリプションを有効にする必要があります。
- ［イベントのサブスクリプション］セクションで、オブジェクトタイプにカーソルを合わせ、［サブスクリプションを表示］をクリックします。
- イベントの横にあるチェックボックスをオンにしてから、テーブルのヘッダーで［アクティベート］をクリックします。
以下のエンドポイントを使用すれば、プログラムに従ってサブスクリプションを作成できます。これらのエンドポイントにリクエストを送信する際は、開発者APIキーを使用する必要があります。
subscriptionオブジェクトには、以下のフィールドを格納できます。
| フィールド | Description |
|---|---|
id
| サブスクリプションごとのIDを表す数値。 |
createdAt
| サブスクリプションが作成された時間（ミリ秒単位）。 |
createdBy
| サブスクリプションを作成したユーザーに関連付けられているユーザーID。 |
能動
| サブスクリプションが有効になっており、アクティブに通知をトリガーしているかどうかを示します。値には |
eventType
| サブスクリプションのタイプ。このセクションの冒頭の表に、利用可能なサブスクリプションタイプが記載されています。 |
propertyName
| サブスクリプションで変更をリッスンする対象のプロパティーの名前。これはプロパティー変更サブスクリプションタイプにのみ必要です。 |
新しいサブスクリプションを作成するには、POSTリクエストをwebhooks/v3/{appId}/subscriptionsに送信します。
リクエスト本文には、以下のフィールドを含めることができます。
| フィールド | Description |
|---|---|
eventType
| サブスクリプションのタイプ。 |
propertyName
| サブスクリプションで変更をリッスンする対象のプロパティーの名前。これはプロパティー変更サブスクリプションタイプにのみ必要です。 |
能動
| サブスクリプションが有効になっており、アクティブに通知をトリガーしているかどうかを示します。値には |
id、createdAt、createdByの各フィールドは自動的に設定されるため、リクエスト本文に含める必要はありません。
以下のリクエスト本文の例をご参照ください。
eventTypeには、前のセクションで定義されている有効なサブスクリプションタイプを指定する必要があります。また、propertyNameは有効なプロパティー名でなければなりません。顧客がこの値に一致するプロパティーを定義していない場合、このサブスクリプションによる通知は行われません。
サブスクリプションを有効化または一時停止するには、PUTリクエストをwebhooks/v3/{appId}/subscriptions/{subscriptionId}に送信します。
リクエスト本文には、以下のフィールドを含めます。
| フィールド | Description |
|---|---|
能動
| サブスクリプションが有効になっており、アクティブに通知をトリガーしているかどうかを示します。値には |
サブスクリプションを削除するには、DELETEリクエストをwebhooks/v3/{appId}/subscriptions/{subscriptionId}に送信します。
アプリのWebhook設定で指定したターゲットURLにあるエンドポイントでは、HubSpotから送信される、JSON形式のデータを含むPOSTリクエストを受信します。
Webhookエンドポイントで取得しているリクエストが実際にHubSpotから送信されたものであることを保証するために、HubSpotは、X-HubSpot-Signatureヘッダーを、貴社のアプリのクライアントシークレットとリクエスト詳細の組み合わせに基づくSHA-256ハッシュにします。詳しくはリクエスト署名の検証方法をご覧ください。
以下の表を使用して、ペイロードに含まれる可能性のあるフィールドの詳細を確認してください。
| フィールド | Description |
|---|---|
objectId
| 作成／変更／削除されたオブジェクトのID。コンタクトの場合はコンタクトID、会社の場合は会社ID、取引の場合は取引ID、コミュニケーションの場合はスレッドIDになります。 |
propertyName
| プロパティー変更サブスクリプションの場合にのみ送信される、変更されたプロパティーの名前。 |
propertyValue
| プロパティー変更サブスクリプションの場合にのみ送信される、通知をトリガーしたプロパティーに新しく設定された値。 |
changeSource
| 変更のソース。コンタクトプロパティー履歴に表示される変更ソースのいずれかを指定できます。 |
eventId
| この通知をトリガーしたイベントのID。この値が一意であることは保証されません。 |
subscriptionId
| イベントに関する通知をトリガーしたサブスクリプションのID。 |
portalId
| イベントが発生した顧客のHubSpotアカウントID。 |
appId
| アプリケーションのID。複数のアプリが同じWebhook URLを示している場合に使用されます。 |
occurredAt
| このイベントが発生した時点のミリ秒単位のタイムスタンプ。 |
eventType
| この通知の対象となっているイベントタイプ。「Webhookサブスクリプション」のセクションに記載されている、サポートされているサブスクリプションタイプのリストを確認してください。 |
attemptNumber
| 0で始まる、貴社のサービスに通知するイベントの試行番号。サービスがタイムアウトした場合や、以下の「再試行」の項目に記載されているエラーが発生した場合、HubSpotは通知の再送信を試みます。 |
messageId
| Webhookでスレッドへの新しいメッセージをリッスンしている場合にのみ送信されます。新しいメッセージのIDです。 |
messageType
| Webhookでスレッドへの新しいメッセージをリッスンしている場合にのみ送信されます。送信するメッセージのタイプです。この値には、 |
| フィールド | Description |
|---|---|
primaryObjectId
| マージ先のID。このIDに該当するレコードが、マージ後に残されます。これは、HubSpotのマージUIでは右側に表示されるレコードに該当します。 |
mergedObjectIds
| マージ先にマージされるレコードを表すIDの配列。これは、HubSpotのマージUIでは左側に表示されるレコードに該当します。 |
newObjectId
| マージの結果として作成されたレコードのID。場合によっては、マージの結果として新しいレコードが作成されることがあるため、これは |
numberOfPropertiesMoved
| マージ中に転送されたプロパティーの数を表す整数。 |
| フィールド | Description |
|---|---|
associationType
| 関連付けは、次のいずれかのタイプになります。
|
fromObjectId
| 関連付けの変更が行われたレコードのID。 |
toObjectId
| 関連付けイベントのセカンダリーレコードのID。 |
associationRemoved
| 以下を表すブール値：
|
isPrimaryAssociation
| 以下を表すブール値：
注意：2つのオブジェクトレコード間にプライマリーの関連付けインスタンスを作成すると、対応する非プライマリーの関連付けも作成されます。これにより、2つのWebhookメッセージが生成される可能性があります。 |
上に示されているように、単一のリクエストによって複数のオブジェクトからなる配列が返されるはずです。一括処理のサイズはさまざまですが、通知は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時間にわたりリクエストの送信間隔を変えながら実行されます。失敗が同時に多発した場合の再試行時刻が完全に同じにならないように、個々の通知にある程度のばらつきが確保されます。
HubSpotがWebhookサブスクリプションを介してお客様のサービスに送信するPOSTリクエストは、お客様のアプリのAPIレート制限には計上されません。
1つのアプリあたり最大1,000件のサブスクリプションを作成できます。この制限を超えて作成しようとすると、以下の本文を含む400 bad requestが返されます。
貴重なご意見をありがとうございました。