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件のコメント
Jay Jayakrishnan
Hi All,
We have an existing JIRA-Zendesk integration in place with few fields from JIRA syncing into Zendesk custom fields. We are now trying to sync “created” date and “last commented” date from JIRA to Zendesk custom ticket fields; but could not find a solution. Zendesk support suggested us that webhooks would be an idea solution to this: "to call the ticket update endpoint and update the Zendesk custom field".
I'm new to webhooks; and not sure how to accomplish this. Any guidance on this would be very helpful.
0
Jon I Sanchez Martinez
I want to create a webhook to create Posts on X. How can I accomplish that? I'm trying to figure out what to do. AFAIK, I must use X's API + OAuth 1a or OAuth 2 authentication methods, but I can't see those options on Zendesk. Before deprecating Destinations, that worked correctly. Can anybody help me out?
0
Jennie Grudi
Getting a 500 internal server error after testing
0
Leonardo Mello
Essa fila de execução existe uma capacidade? Pelo fato de não executar imediatamente a tarefa, quanto tempo pode demorar a execução? Se existe uma capacidade e um tempo, tem como aumentar a capacidade e diminuir o tempo de execução (talvez em um plano enterprise)?
0
Madhan Thangadurai
Hi all
Do webhooks support bearer tokens (first time), i.e. adding the token for the first time in Admin Center -> Apps and Integrations -> Webhooks -> Create Webhook ? Also does it refresh the tokens automatically when it expires ?
0
Ivan Miquiabas
Thanks for reaching out!
What Peter said was exactly the best explanation regarding this question. Thank you also for sharing your workaround. Although it does send a fair warning. Please do reach out to us again if you encounter any issues, rest assured we can create a ticket on your behalf and assign it to one of our advocates!
Cheers!
0
Simon Pledger
Hi Peter
Thanks for your helpful reply and advice. I'll certainly explore Let's Encrypt going forward.
In the mean time I have actually managed to workaround the problem by opening an additional non secure http port on my same webapplication server and changing my webhook to call the http version of the endpoint instead. Zendesk isn't too happy about me using an http endpoint in my webhook and puts a warning under the field :-) ... but it does now work, and circumvents the ssl validation issue for my local testing.
Best regards
Simon
0
Peter Hochstrasser
Hi Simon Pledger
The problem here is that the Zendesk infrastructure is public, and, to my knowledge, you as a user of a Zendesk subdomain do not have a way to add your own certificates (or trust chains). Therefore, you are required to have a "real" certificate that Zendesk can authenticate against a standard set of CA certificates and intermediate certificates.
A cheap (free) and safe way to get such a certificate is to use Let's Encrypt on your end, so on your local web service. Since Zendesk uses this scheme itself, it is very likely that this will work ;-).
Yours truly
Peter
0
Simon Pledger
Hi everyone
I wish to have a webhook call an SSL endpoint on my local development machine, whose target webapplication uses a self signed certificate.
The webhook fails and the activity page reports " x509: certificate signed by unknown authority".
Is there a way to configure Zendesk to allow webhooks to call SSL endpoints with self signed certificates.
In contrast, URL Targets work fine and I have never had issues with them calling self signed certificate SSL endpoints. So I am a little puzzled why this restriction only seems to exist on webhooks. It is sadly preventing me from doing any local development and prototyping at the moment
Thanks in advance for any help
Simon
0
JR Lausin
You must be an admin or an agent in a custom role with permission to create webhooks.
Please check this article.
https://support.zendesk.com/hc/en-us/articles/4408839108378-Creating-webhooks-to-interact-with-third-party-systems#topic_qbn_v4w_dpb
0
サインインしてコメントを残します。