Webhooks journal API

Documentation Index

Fetch the complete documentation index at: https://developers.hubspot.jp/docs/llms.txt

Use this file to discover all available pages before exploring further.

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

​

スコープ

• 公開アプリの設定UIでサブスクリプションを作成する場合、サブスクリプションの作成を完了する前に、［新しいWebhook配信登録を作成］パネルで必要なスコープを追加するように求められます。
• POSTリクエストを/webhooks/v3/{appId}/subscriptionsエンドポイントに送信してサブスクリプションを作成する場合、レスポンスに含まれるエラーに、公開アプリの設定UIで設定する必要があるスコープの名前が示されます。
• アプリですでにWebhookを使用している場合、アクティブなWebhookサブスクリプションで必要とされているスコープを削除するには、その前に、該当するWebhookサブスクリプションを一時停止して削除する必要があります。
• Webhookサブスクリプションタイプごとに必要となるスコープは、下にある表で確認できます。

​

Webhookの設定

​

開発者アカウントでの設定の管理

• 開発者アカウントで、［アプリ］ダッシュボードに移動します。
• Webhookを設定する対象のアプリの名前をクリックします。

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

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

​

APIによる設定の管理

// PUT request to https://api.hubapi.com/webhooks/v3/{appId}/settings

{
  "throttling": {
    "period": "SECONDLY",
    "maxConcurrentRequests": 10
  },
  "targetUrl": "https://www.example.com/hubspot/target"
}

​

Webhookサブスクリプション

• 2つのコンタクトが関連付けられると、contact.associationChangeのサブスクリプションによって、それぞれcontact 1 to contact 2とcontact 2 to contact 1を表す2つのイベントがトリガーされます。
• contact.associationChangeとcompany.associationChangeの2つのWebhookサブスクリプションを使用している場合、会社が関連付けられると、2つのイベントを受信します。これらのイベントは、それぞれcontact 1 to company 1、company 1 to contact 1を表します。

• num_unique_conversion_events
• hs_lastmodifieddate

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

​

開発者アカウントでのサブスクリプションの作成

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

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

• ［配信登録］をクリックします。

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

​

APIを使用したサブスクリプションの作成

​

サブスクリプションの取得

// Example GET request to https://api.hubapi.com/webhooks/v3/{appId}/subscriptions

[
  {
    "id": 25,
    "createdAt": 1461704185000,
    "createdBy": 529872,
    "eventType": "contact.propertyChange",
    "propertyName": "lifecyclestage",
    "active": false
  },
  {
    "id": 59,
    "createdAt": 1462388498000,
    "createdBy": 529872,
    "eventType": "company.creation",
    "active": false
  },
  {
    "id": 108,
    "createdAt": 1463423132000,
    "createdBy": 529872,
    "eventType": "deal.creation",
    "active": true
  }
]

​

新規サブスクリプションの作成

// Example POST request to https://api.hubapi.com/webhooks/v3/{appId}/subscriptions

{
  "eventType": "company.propertyChange",
  "propertyName": "companyname",
  "active": false
}

​

サブスクリプションの更新

​

サブスクリプションの削除

​

Webhookペイロード

//
[
  {
    "objectId": 1246965,
    "propertyName": "lifecyclestage",
    "propertyValue": "subscriber",
    "changeSource": "ACADEMY",
    "eventId": 3816279340,
    "subscriptionId": 25,
    "portalId": 33,
    "appId": 1160452,
    "occurredAt": 1462216307945,
    "eventType": "contact.propertyChange",
    "attemptNumber": 0
  },
  {
    "objectId": 1246978,
    "changeSource": "IMPORT",
    "eventId": 3816279480,
    "subscriptionId": 22,
    "portalId": 33,
    "appId": 1160452,
    "occurredAt": 1462216307945,
    "eventType": "contact.creation",
    "attemptNumber": 0
  }
]

​

プライバシー規則に準拠したコンタクトの削除

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

​

セキュリティー

​

再試行

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

​

制限

//
{
  "status": "error",
  "message": "Couldn't create another subscription. You've reached the maximum number allowed per application (1000).",
  "correlationId": "2c9beb86-387b-4ff6-96f7-dbb486c00a95",
  "requestId": "919c4c84f66769e53b2c5713d192fca7"
}