Web開発者は、Webhookを使用して別のシステムでの動作を呼び出します。たとえば、Webhookを使って以下のようなことができます。
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」を参照してください。
トリガまたは自動化に接続する
-
JSON
-
XML
-
フォームエンコードされたコンテンツ
Webhookをトリガまたは自動化に接続するときに、リクエストのコンテンツを定義します。POST、PUT、またはPATCH HTTPメソッドをJSONまたはXMLリクエスト形式で使用するWebhookの場合、コンテンツはリクエストペイロードです。他のHTTPメソッドまたは形式を使用するWebhookには、リクエストペイロードは含まれません。代わりに、2つのキー値文字列の配列としてカスタムURLパラメータを追加することができます。リクエストペイロードやURLパラメータを定義する場合、使用可能な任意のコンテンツプレースホルダを使用して、チケットデータをリクエストに挿入することができます。
WebhookのリクエストペイロードまたはURLパラメータは256KB未満でなければなりません。
Webhookの順序付けと再試行
イベント、トリガ、または自動化がWebhookを呼び出すと、実行されるWebhookジョブがキューに入りますが、実際にはジョブをすぐに実行するわけではありません。Webhookジョブは独立して実行されるため、Webhookが特定の順序で実行される保証はありません。
Webhookのリクエストは、エンドポイントが特定のHTTPレスポンスコードを返した場合、自動的に最大3回まで再試行されます。ターゲットとは異なり、リクエストが連続して失敗してもWebhookは無効になりません。再試行シナリオの詳細と例については、開発者向けドキュメントの「Webhookの監視」を参照してください。
Webhookの作成
Webhookは管理センターで作成できます。
Webhookを作成するには
- 管理センターで、サイドバーにある「
アプリおよびインテグレーション」をクリックし、「アクションおよびWebhook」>「Webhook」を選択します。 - 「Webhookを作成する」をクリックします。
- WebhookでZendeskイベントを1つ以上受信登録するには、Zendeskイベントを選択し、ドロップダウンからイベントタイプを1つ以上選択します。
- Webhookをトリガまたは自動化に接続するには、「トリガまたは自動化」を選択します。
- 「次へ」をクリックします。
- Webhookの「名前」と「説明」を入力します。
- サードバーティサービス/システムとの統合に使用されるエンドポイントURLを入力します。詳しくは「Webhookのエンドポイント」を参照してください。
サードパーティと統合するためにWebhookを設定する場合、サードパーティのドキュメントの参照が必要になることもあります。
- Webhookの「リクエスト方法」および「リクエスト形式」を選択します。
- Webhookの認証方法を選択し、必要な追加情報を入力します。詳しくは「Webhookの認証」を参照してください。
- （オプション）「ヘッダーを追加」をクリックしてカスタムヘッダーを追加し、「ヘッダー名」と「値」を入力します。「別のヘッダーを追加」をクリックして、あと4つまでヘッダーを追加できます。詳しくは「カスタムWebhookヘッダー」を参照してください。メモ：カスタムヘッダーには個人情報を含めないようにしてください。
- （オプション）「Webhookをテスト」をクリックして、期待どおりに動作していることを確認します。
- 「Webhookを作成する」をクリックして、Webhookを作成します。
- トリガと自動化の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文字に対応しています。
- 次のヘッダーはサポートされません。
- accept-charset
- accept-encoding
- connection
- content-encoding
- content-length
- content-md5
- content-type
- date
- expect
- forwarded
- host
- keep-alive
- max-forwards
- origin
- proxy-authenticate
- referer
- server
- te
- trailer
- transfer-encoding
- upgrade
- user-agent
- via
- www-authenticate
- zendesk-api-version
- zendesk-ep
- また、ヘッダーを次のプレフィックスで始めることはできません。
- access-control
- x-amzn
- x-apigw
- x-datadog
- x-envoy
- x-forwarded
- x-zendesk
Webhookの認証
Webhookをセキュアなエンドポイントと統合する場合、WebhookおよびWebhookが送信するデータを認証するためのオプションが3つあります。エンドポイントの認証要件についてサードパーティのドキュメントを参照するか、またはチーム内の開発者と協力してWebhookに適した認証方法を選ぶことができます。
- なし：認証が設定されておらず、要求されません。
- APIキー：APIキーを使用して、Webhookを認証します。
- 基本認証：ユーザー名とパスワードを使用してWebhookを認証します。
- ベアラートークン：OAuthアクセストークンを使用してWebhookを認証します。
Webhook認証についての開発者向け情報は、「Webhook security and authentication（Webhookのセキュリティと認証）」を参照してください。
セキュリティを強化するために、Webhookの署名を確認することもできます。詳細については、「Verifying webhook authenticity」を参照してください。
Webhookをトリガや自動化に接続する
トリガと自動化のWebhookを呼び出すには、まずWebhookをトリガまたは自動化に接続する必要があります。トリガや自動化は、Webhookの呼び出しが行われる状況を指定します。
WebhookをSupportのトリガに接続するには
- 管理センターで、サイドバーの「
オブジェクトとルール」をクリックし、「ビジネスルール」>「トリガ」を選択します。 -
トリガを新規作成するか、オプションアイコン（
）にマウスのポインタを合わせて「編集」をクリックし、既存のトリガを編集します。 - 「アクション」で、「アクションを追加」をクリックします。「アクティブなWebhookを通知する」を選択し、Webhookを選択します。
- Webhookのリクエスト形式に応じて、WebhookのリクエストペイロードまたはURLパラメータを入力します。ペイロードまたはパラメータは256 KB未満でなければなりません。
- 「保存」をクリックします。
- 管理センターで、サイドバーの「 オブジェクトとルール」をクリックし、「ビジネスルール」>「自動化」を選択します。
-
自動化を新規作成するか、オプションアイコン（）にマウスのポインタを合わせて「編集」をクリックし、既存の自動化を編集します。
- 「これらのアクションを実行」で、アクションの追加アイコン（
）をクリックします。「通知:アクティブなWebhookを通知する」を選択して、Webhookを選択します。 - Webhookのリクエスト形式に応じて、WebhookのリクエストペイロードまたはURLパラメータを入力します。ペイロードまたはパラメータは256 KB未満でなければなりません。
- 「送信」をクリックします。
Webhookをテストする
管理センターでは、さまざまなイベントソースやリクエストを使ってWebhookをテストすることができます。テスト専用の既存のWebhookにアクセスするだけでなく、作成中または編集中にWebhookをテストすることもできます。
Webhookをテストするには
- 管理センターで、サイドバーにある「 アプリおよびインテグレーション」をクリックし、「アクションおよびWebhook」>「Webhook」を選択します。
- リストでWebhookを見つけ、Webhookの行にあるオプションメニューアイコン（）をクリックして、「Webhookをテスト」をクリックします。
- 「Webhookをテスト」パネルで、テストするイベントを選択します。これは、エンドポイントURLのテストに使用できるサンプルリクエストです。
- テストリクエストの詳細情報（リクエストボディ、パラメーター、ヘッダなど）を入力します。
- 「テストを送信」をクリックします。レスポンスは、テストリクエストの下のパネルに表示されます。
0件のコメント