日本語
  1. Zendeskヘルプ
  2. アプリおよびインテグレーション
  3. アプリおよびインテグレーション関連のドキュメント
  4. Zendeskの拡張

サードパーティシステムと対話するためのWebhookの作成

Jacquelyn Brewer
  • 編集済み
Zendesk Documentation Team

ファストパス：管理センター >「アプリおよびインテグレーション」>「Webhook」>「Webhook」
Webhookは、Zendesk Supportでのアクティビティへの応答として、指定したURLにHTTPリクエストを送信します。たとえば、ユーザーが削除されたときや、新しいチケットが作成されたときにリクエストを送信するようにWebhookを設定することができます。

Web開発者は、Webhookを使用して別のシステムでの動作を呼び出します。たとえば、Webhookを使って以下のようなことができます。

  • 緊急のチケットが作成された場合に、Slackでチームに警告する
  • チケットを解決した後、チケットの情報をAsanaのドキュメントチームに渡す
  • 重要なチケットイベントに関して、自社のバックエンドサービスに通知する

Webhookを作成するには、管理者権限またはトリガの作成権限のあるカスタムロールのエージェントである必要があります。トライアルアカウントには、最大10個のWebhook制限と、毎分60回のAPIコール制限があります。

この記事では、次のトピックについて説明します。

Webhookについて

WebhookをZendesk Supportのアクティビティに接続するには、2つの方法があります。

  • Webhookを1つまたは複数のZendeskイベントに登録する。この接続方法を使用して、組織やユーザーのアクティビティに基づいてリクエストを送信します。サポートされているイベントの種類の一覧は、APIリファレンスの「Webhook event types」を参照してください。
  • Webhookをトリガまたは自動化に接続する。この接続方法を使用して、チケットのアクティビティに基づいてリクエストを送信します。

Zendeskのイベントを受信登録されているWebhookは、トリガや自動化に接続できません。同様に、トリガまたは自動化に接続されているWebhookは、Zendeskイベントを受信登録できません。既存のWebhookの接続方法は変更できません。

Zendeskイベントを受信登録する

1つ以上のZendeskイベントを受信登録しているWebhookは、常にPOST HTTPメソッドを使用してリクエストを送信します。リクエストには、イベントのデータを含むJSONペイロードが含まれます。リクエストのHTTPメソッドまたはペイロードは変更できません。イベントペイロードスキーマの詳細については、APIリファレンスの「Webhook event types」を参照してください。

トリガまたは自動化に接続する

Webhookがトリガまたは自動化に接続されている場合は、WebhookのリクエストのHTTPメソッド、形式、およびコンテンツをカスタマイズできます。Webhookを作成するときに、HTTPメソッドとリクエスタ本文の形式を選択します。トリガまたは自動化に接続されたWebhookは、次のリクエスト本文形式をサポートします。

  • JSON

  • XML

  • フォームエンコードされたコンテンツ

Webhookをトリガまたは自動化に接続するときに、リクエストのコンテンツを定義します。POST、PUT、またはPATCH HTTPメソッドをJSONまたはXMLリクエスト形式で使用するWebhookの場合、コンテンツはリクエストペイロードです。他のHTTPメソッドまたは形式を使用するWebhookには、リクエストペイロードは含まれません。代わりに、2つのキー値文字列の配列としてカスタムURLパラメータを追加することができます。

リクエストのペイロードやURLパラメータを定義する場合、使用可能な任意のコンテンツプレースホルダを使用して、チケットデータをリクエストに挿入することができます。

Webhookの順序付けと再試行

イベント、トリガ、または自動化がWebhookを呼び出すと、実行されるWebhookジョブがキューに入りますが、実際にはジョブをすぐに実行するわけではありません。Webhookジョブは独立して実行されるため、Webhookが特定の順序で実行される保証はありません。

Webhookのリクエストは、エンドポイントが特定のHTTPレスポンスコードを返した場合、自動的に最大3回まで再試行されます。ターゲットとは異なり、リクエストが連続して失敗してもWebhookは無効になりません。再試行シナリオの詳細と例については、開発者向けドキュメントの「Webhookの監視」を参照してください。

Webhookの作成

Webhookは管理センターで作成できます。

Webhookを作成するには

  1. 管理センターで、サイドバーにある「 アプリおよびインテグレーション」をクリックし、「Webhook」>「Webhook」を選択します。
  2. 「Webhookを作成する」をクリックします。
    • 1つ以上のZendeskイベントをWebhookで受信登録するには、Zendeskイベントを選択し、ドロップダウンからイベントタイプを1つ以上選択します。
    • Webhookをトリガまたは自動化に接続するには、「トリガまたは自動化」を選択します。
  3. 「次へ」をクリックします。
  4. Webhookの「名前」と「説明」を入力します。
  5. サードバーティサービス/システムとの統合に使用されるエンドポイントURLを入力します。詳しくは「Webhookのエンドポイント」を参照してください。

    サードパーティと統合するためにWebhookを設定する場合、サードパーティのドキュメントの参照が必要になることもあります。

  6. Webhookの「リクエスト方法」および「リクエスト形式」を選択します。
  7. Webhookの認証方法を選択し、必要な追加情報を入力します。詳しくは「Webhookの認証」を参照してください。
  8. （オプション）「ヘッダーを追加」をクリックしてカスタムヘッダーを追加し、「ヘッダー名」と「値」を入力します。「別のヘッダーを追加」をクリックして、あと4つまでヘッダーを追加できます。詳しくは「カスタムWebhookヘッダー」を参照してください。
    メモ：カスタムヘッダーには個人情報を含めないようにしてください。
  9. （オプション）「Webhookをテスト」をクリックして、期待どおりに動作していることを確認します。
  10. 「Webhookを作成する」をクリックして、Webhookを作成します。
  11. トリガと自動化のWebhookの場合、Webhookをトリガまたは自動化に接続する必要があります。詳しくは「Webhookをトリガや自動化に接続する」を参照してください。トリガまたは自動化を接続したら、「Webhookを作成する」ページに戻り、「設定を完了」をクリックします。

Webhookを作成したら、管理センターの「Webhook」ページからその詳細、サブスクリプション、およびアクティビティを表示できます。詳しくは「Webhookの管理」を参照してください。

Webhookのエンドポイント

Webhookは、作成時に指定したエンドポイントURLからリクエストを送信します。エンドポイントURLは、https://www.yourdomain.com/pathの形式で指定します。

必須ではありませんが、セキュアHTTP（HTTPS）の使用を推奨します。セキュアなエンドポイントURLを提供することで、認証を有効にし、データを安全に渡すことができます。

カスタムWebhookヘッダー

カスタムヘッダーは、Webhookが送信するリクエストに追加情報を含める方法を提供し、固有のWebhookヘッダー要件がある一部のサードパーティサービスに簡単に接続できるようにします。なお、カスタムヘッダーには次の要件および制限があります。

  • カスタムヘッダーを使用するには、セキュア（HTTPS）エンドポイントURLを使用する必要がある。
  • ヘッダー名は一意の名前で、128文字以内にする必要があります。すべての英数字US ASCII文字に加え、「!」、「#」、「$」、「%」、「&」、「'」、「*」、「+」、「-」、「.」、「^」、「_」、「`」、「|」、「 ~」の各記号に対応しています。
  • ヘッダー値は最大1,000文字で、0x20～0x7EまでのすべてのUS ASCII文字に対応しています。

Webhookの認証

Webhookをセキュアなエンドポイントと統合する場合、WebhookおよびWebhookが送信するデータを認証するためのオプションが3つあります。エンドポイントの認証要件についてサードパーティのドキュメントを参照するか、またはチーム内の開発者と協力してWebhookに適した認証方法を選ぶことができます。

  • なし：認証が設定されておらず、要求されません。
  • APIキー：APIキーを使用して、Webhookを認証します。
  • 基本認証：ユーザー名とパスワードを使用してWebhookを認証します。
  • ベアラートークン：OAuthアクセストークンを使用してWebhookを認証します。

Webhook認証についての開発者向け情報は、「Webhook security and authentication（Webhookのセキュリティと認証）」を参照してください。

Webhookをトリガや自動化に接続する

トリガと自動化のWebhookを呼び出すには、まずWebhookをトリガまたは自動化に接続する必要があります。トリガや自動化は、Webhookの呼び出しが行われる状況を指定します。

WebhookをSupportのトリガに接続するには

  1. 管理センターで、サイドバーの「 オブジェクトとルール」をクリックし、「ビジネスルール」>「トリガ」を選択します。
  2. トリガを新規作成するか、オプションアイコン（）にマウスのポインタを合わせて「編集」をクリックし、既存のトリガを編集します。
  3. トリガの場合、「アクション」で「アクションを追加」をクリックします。「アクティブなWebhookを通知する」を選択し、Webhookを選択します。「保存」をクリックします。
WebhookをSupportの自動化に接続するには
  1. 管理センターで、サイドバーの「 オブジェクトとルール」をクリックし、「ビジネスルール」>「自動化」を選択します。
  2. 自動化を新規作成するか、オプションアイコン（）にマウスのポインタを合わせて「編集」をクリックし、既存の自動化を編集します。
  3. 自動化の場合は、「これらのアクションを実行」で、アクションの追加アイコン（）をクリックします。「通知：アクティブなWebhookを通知する」を選択して、Webhookを選択します。「送信」をクリックします。

Webhookをテストする

管理センターでは、さまざまなイベントソースやリクエストを使ってWebhookをテストすることができます。テスト専用の既存のWebhookにアクセスするだけでなく、作成中または編集中にWebhookをテストすることもできます。

Webhookをテストするには

  1. 管理センターで、サイドバーにある「 アプリおよびインテグレーション」をクリックし、「Webhook」>「Webhook」を選択します。
  2. リストでWebhookを見つけ、Webhookの行にあるオプションメニューアイコン（）をクリックして、「Webhookをテスト」をクリックします。
  3. 「Webhookをテスト」パネルで、テストするイベントを選択します。これは、エンドポイントURLのテストに使用できるサンプルリクエストです。
  4. テストリクエストの詳細情報（リクエストボディ、パラメーター、ヘッダなど）を入力します。
  5. 「テストを送信」をクリックします。レスポンスは、テストリクエストの下のパネルに表示されます。
2
ページの先頭へ戻る

0 コメント

サインインしてコメントを残してください。

関連記事

Powered by Zendesk