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のテストに使用できるサンプルリクエストです。
- テストリクエストの詳細情報(リクエストボディ、パラメーター、ヘッダなど)を入力します。
- 「テストを送信」をクリックします。レスポンスは、テストリクエストの下のパネルに表示されます。
81件のコメント
Bernard Ugalde
Can anyone confirm if a light agent can authenticate for webhooks? We downgraded a system account from Agent to light agent, and now the activity for the webhook shows the following:

0
Peter Hochstrasser
Hi Caroline Scott
It would be best if you find a way to do this in Zendesk using built-in functionality (Yes, that's me who uses lots of webhooks and API scripts to implement things Zendesk has "forgotten" to add for years).
The main challenge here is that there's no functionality to send a mail TO the light agents instead of just CCing them (it doesn't matter if you're on Followers or not).
Do you have numbers, e.g.,
Depending on these numbers,
The API is pretty nice to use, but if you're on your own with no coding experience, you might want to look around for a partner who would be able to implement a solution for you. Usually, the Zendesk Reps are pretty helpful in that respect.
Let me add a word of caution: You have a problem, and you need a solution. Therefore, try to sketch the solution as precisely as possible - otherwise, it's hard to get a good solution implemented within a reasonable timeframe and budget.
0
Caroline Scott
Can anyone on this thread help me with an issue? I have several teams who want to be able to create a chaser to LIGHT AGENTS (or any agent type). We have lots (1000s) of light agents and they do not log in to Zendesk to update tickets, they respond via email. Currently we cc them into a ticket to ask via internal notes for advice/information and we would like to be able automatically contact them to remind them to reply after so many days. We are moving to the Followers experience very soon so we will be using the followers field to contact them instead of the CC field.
I am not a developer, I do not have access to a developer, I also am not confident in using the API. I have raised this need with Zendesk several times now with no solution that I can implement easily.
0
Peter Hochstrasser
Hi
The syntax for the Token is /token, not /API
0
Sharuk Ahmad
Hi All - I am trying to setup a webhook to automatically CC one end user each time a ticket is submitted. My initial problem is that I keep getting the following msg each time I am trying to test the webhook. Any help would be appreciated.
Response Body: {"error":"Couldn't authenticate you"}
My current Webhook setup:
Endpoint URL*: https://myorg.zendesk.com/api/v2/tickets/{{ticket.id}}.json
Request Method: PUT
Request Format: JSON
Authentication: Basic authentication
Username: myemail.org/API Token
Password: API Token
Note: I created a new API Token for Webhook
0
Ankit Jain
When devs/we read this or want to try out webhooks, devs don't have an HTTP endpoint to review incoming payloads from their instance of Zendesk. It takes some time to deploy an HTTP endpoint to inspect all types of incoming payloads. As zendesk is popular, the following information shall help fellow developers. For the authors, this suggestion should be moved to "Testing a webhook" section.
---
Typically when you want to start with webhook developments, you would like to know some or all possible payloads that zendesk can send. You shall need an HTTP endpoint to capture and review these incoming payloads. I suggest some HTTP bin kind of tools which are very popular and handy to get started in no time.
1. Beeceptor - https://beeceptor.com/ - Gives you an HTTP domain that you can enter in Zendesk and start receiving payloads. Using its mock feature you can respond with custom payloads/failures as well. Quite handy to start webhook development
2. RequestBIN - https://pipedream.com/requestbin - Gives you an HTTP endpoint to capture any incoming request. It always send 200 OK status.
0
Dane
This will entirely depend on the format of JSON will be accepted by it. As for slack the payload is like the payload below.
0
Andrew France
Hi all
I am new to webhooks, I can successfully send the json to a 3rd party system but my json file is empty. From the documentation it appears I need to add placeholders into the json format when creating the webhook. Am I correct in my thinking, if so what would an example look like?
Andrew
0
Jacob the Moderator
This announcement seems relevant to a lot of comments here:
Announcing API key authentication and custom headers for webhooks
0
Brett Bowser
I'd recommend reaching out to our Customer Support team regarding this issue so they can take a look at your account. More information on contacting their team here: Contact Zendesk Customer Support
Hope this helps!
0
サインインしてコメントを残します。