HubSpotワークフローでWebhookを使用する

ワークフローでWebhookを使用することにより、HubSpotと他の外部ツールの間で情報を送信したり取得したりします。Webhookにはさまざまな用途がありますが、一般的なWebhookの使用例としては次のようなものがあります。

• コンタクトがサイト内のフォームから情報を送信したときに、HubSpotのコンタクトデータをCRMなどの外部システムに送信する。

• 取引データを外部出荷処理システムに送信して注文書を作成する。

• 外部システムから社内のチャットストリームにチャットアラートを送信し、重要なことが起こったことを従業員に通知する。

• 別のシステムからデータを取得してHubSpotのレコードを更新する。 

ワークフローを使用して、POSTとGETの両方のリクエストを送信できます。HubSpotは、Webhookトラフィックを他のワークフロープロセスから切り離して制御します。これは、ワークフローとWebhookのパフォーマンスを向上させるために行います。Webhookが遅い場合やタイムアウトした場合は、ワークフローアクションの実行に予想より長い時間がかかります。

注：HubSpotは、失敗したWebhookについて、失敗の1分後から最大3日間に渡って再試行します。その後の失敗は、徐々に間隔を延ばして再試行されます。再試行の間隔は最大で8時間になります。HubSpotの開発者ドキュメントで、特定のエラーコード例外について確認する。

開発者WebhookドキュメントでWebhookの詳細をご確認ください。HubSpotでのWebhookの具体的な実装についてご不明な点がございましたら、HubSpot開発者フォーラムをご利用ください。

 ワークフローでWebhookをセットアップする

• HubSpotアカウントにて、［自動化］＞［ワークフロー］の順に進みます。
• ワークフローの名前をクリックします。
• +アイコンをクリックして、アクションを追加します。
• 右側のパネルで［Webhookを送信］を選択します。
• ［メソッド］ドロップダウンメニューをクリックし、［POST］または［GET］を選択します。 
• WebhookURLを入力します。WebhookURLには安全なプロトコルという制限があり、HTTPSで始まる必要があります。特定の情報を要求するには、「Webhook URL」に?queryparameter=abcのようなクエリーパラメーターを追加できます。クエリーパラメーターが追加されなかった場合は、汎用のPOSTリクエストまたはGETリクエストが送信されます。  
• Webhookへのリクエストを認証するための認証タイプを次のように設定します。 
  • Webhookヘッダーでリクエスト署名を使用するには： 
    • ［認証タイプ］ドロップダウンメニューをクリックします。次に、［ヘッダーにリクエスト署名を含める］を選択します。
    • 次に、［HubSpotアプリID］を入力します。リクエスト署名を確認する方法をご確認ください。

• • また、APIキーや開発者アカウントで作成された公開アプリ認証に使用することもできます。

注：2022年11月30日以降、HubSpot APIキーは廃止され、サポートされなくなります。HubSpotワークフローでは、引き続き外部APIキーを認証に使用することができます。

• • • 認証にAPIキーを使用するとき、使用する「APIキー名」と「APIキーの場所」はWebhookの設定方法に応じて異なります。セキュリティー上の理由から、APIキーはいかなるテストリクエストにも表示されません。APIキーを使用するには： 
      • ［認証タイプ］ドロップダウンメニューをクリックします。次に、［APIキー］を選択します。 

• • • • ［APIキー名］を入力します。
      • ［APIキーの場所］ドロップダウンメニューをクリックします。次に、［クエリーパラメーター］または［リクエストヘッダー］のいずれかを選択します。HubSpotでAPIキーを使用する方法について、詳しくはこちらをご覧ください。
    • いずれかのHubSpot APIにリクエストを送る場合：
      • ［APIキー］ドロップダウンメニューをクリックし、シークレットを1つ選択します。「シークレット」値は、「Bearer （自分のトークン名）」という形式でなければなりません。
      • APIキー名の値を［Authorization］に設定します。
      • 「APIキーの場所」の値を［リクエストヘッダー］に設定します。
• POSTリクエストを設定する場合は、CRMレコードのすべてのプロパティーを含めるか、それとも特定のプロパティーのみを送信するかを次のように選択できます。
  • すべてのプロパティーを含めるには、［リクエスト本文をカスタマイズ］セクションで［全てのプロパティーを含める］を選択します。  
  • 特定のプロパティーだけを含めるには：
    
    • ［リクエスト本文をカスタマイズ］セクションで、［特定のプロパティーを選択］を選択します。
    • ［プロパティーの選択］ドロップダウンメニューをクリックします。次に、［このワークフローの［オブジェクト］］をクリックし、プロパティーを1つ選択します。
    • Webhookでプロパティーの名前を変更するには、［プロパティー名］テキストフィールドを編集します。ここではPOSTリクエストのプロパティー名のみが更新されます。HubSpotのプロパティー名や内部名は更新されません。  
    • 別のプロパティーを追加するには、［プロパティーを追加］をクリックします。
    • プロパティーを削除するには、deleteゴミ箱アイコンをクリックします。
         

• GETリクエストを設定する場合は、クエリーパラメーターとしてプロパティーを次のように使用することができます。
  
  • ［クエリーパラメーター］セクションで、［プロパティーの選択］ドロップダウンメニューをクリックします。次に、［このワークフローの［オブジェクト］］をクリックし、プロパティーを1つ選択します。
  • クエリーパラメーターでプロパティーの名前を変更するには、［プロパティー名］テキストフィールドを編集します。ここではGETリクエストのプロパティー名のみが更新されます。HubSpotのプロパティー名や内部名は更新されません。  
• • 別のプロパティーを追加するには、［クエリーパラメーターを追加］をクリックします。
  • プロパティーを削除するには、deleteゴミ箱アイコンをクリックします。     
• ［保存］をクリックします。
  
  

注：複数の出力を選択するには、レスポンスがJSONオブジェクトとして構造化されている必要があります。

POSTリクエストをカスタマイズする

POSTリクエストを設定する場合は、CRMレコードのすべてのプロパティーを含めるか、それとも特定のプロパティーのみを送信するかを次のように選択できます。

• すべてのプロパティーを含めるには、［リクエスト本文をカスタマイズ］セクションで［全てのプロパティーを含める］を選択します。  
• 特定のプロパティーだけを含めるには：
  
  • ［リクエスト本文］セクションで、［リクエスト本文をカスタマイズ］を選択します。
  • キーと値を入力します。
  • Webhookでプロパティーの名前を変更するには、［キー］テキストフィールドを編集します。ここではPOSTリクエストのプロパティー名のみが更新されます。HubSpotのプロパティー名や内部名は更新されません。  
  • 別のプロパティーを追加するには、［プロパティーを追加］をクリックします。
  • プロパティーを削除するにはdeleteゴミ箱アイコンをクリックします。
    
    

GETリクエストをカスタマイズする

GETリクエストを設定する場合は、クエリーパラメーターとしてプロパティーを次のように使用して特定のデータを取得できます。 

• ［クエリーパラメーター］セクションでキーを入力し、プロパティーを1つ選択します。
• クエリーパラメーターでプロパティーの名前を変更するには、［プロパティー名］テキストフィールドを編集します。ここではGETリクエストのプロパティー名のみが更新されます。HubSpotのプロパティー名や内部名は更新されません。  
• 別のプロパティーを追加するには、［プロパティーを追加］をクリックします。
• プロパティーを削除するには、deleteゴミ箱アイコンをクリックします。     
• ドロップダウンメニューから［認証タイプ］を選択します。
• ［保存］をクリックします。
  
  

HubSpot内でWebhookをテストする

「POST」または「GET」Webhookをセットアップする際に、Webhookレスポンスを確認するためのテストを実行できます。テスト中は第三者へのデータの送信と第三者からのデータの取得が行われますが、HubSpot内の既存のレコードには影響しません。認証にAPIキーを使用している場合、APIキーはいかなるテストリクエストにも表示されません。

Webhookのテスト後に、その後のワークフローで入力として使用するために出力するフィールドを選択できます。すべてのレスポンスで使用可能な出力のみを選択します。出力がその後のアクションで使用されるものの、レスポンスで使用できない場合、そのアクションは失敗します。   

• サイドパネルで［テストアクション］をクリックし、セクションを展開します。 
• ［オブジェクト］ドロップダウンメニューをクリックし、テストするレコードを選択します。
• ［テスト］をクリックします。 
• Webhookの詳細を確認するには、［レスポンス］タブまたは［リクエスト］タブを選択します。各タブでは、［すべてを開く］をクリックするとすべてのセクションが展開され、［すべて折りたたむ］をクリックするとすべてのセクションが折りたたまれます。
  
  • ［レスポンス］タブでは、［headers:］または［body:］をクリックすると、それぞれのセクションが展開されます。 
  • ［リクエスト］タブでは、［httpHeaders:］をクリックすると、そのセクションが展開されます。
    
    

外部でWebhookをテストする

Webhookアクションを含むワークフローを作成したら、ダミーのWebhook URLを使用して、簡単なテストを実行できます。

• ブラウザーでhttps://webhook.siteに移動し、一意のURLをコピーします。
• Webhookアクションの［WebhookURL］フィールドに、コピーしたURLを貼り付けます。

• ワークフローがオンになると、テストコンタクトを手動で登録できます。 

POSTリクエストを含むWebhookアクションがトリガーされた場合は、コンタクトに関するすべての情報（フォーム送信、リストのメンバーシップ、すべてのコンタクトプロパティー値など）を格納したJSONレスポンス本文がWebhookに送信されます。レコードを受け取ったシステムは、そのJSONデータを解析し、システム固有のアプリケーションで使用します。

GETリクエストを含むWebhookアクションがトリガーされた場合は、追加のクエリーパラメーターが適用されていない限り、汎用のGETリクエストが送信されます。   

注：履歴プロパティー値はコンタクトベースのワークフローでのみ返されます。他のすべてのワークフロータイプで使用されるWebhookは最新の値のみを返します。

ワークフローWebhookでリクエスト署名を確認する

［Webhookの実行］アクションの［認証］セクションで、［リクエスト署名］を選択した場合、HubSpotはWebhookのX-HubSpot-Signatureヘッダーに、アプリケーションのアプリシークレット、HTTPメソッド、URI、未解析の本文をつなげたSHA-256ハッシュを取り込みます。開発者ドキュメントで詳細をご確認ください。

URLで受信したリクエストの送信元がHubSpotであることを確認するには、次のようにします。

• 開発者アカウントを所有します。所有していない場合は、開発者アカウントを登録します。
• アプリを所有します。所有していない場合は、アプリを作成する方法をご確認ください。
• 署名のハッシュ値を確認します。