Creating and monitoring webhooks
A webhook sends an HTTP request to a specified URL in response to activity in Zendesk Support. For example, you can configure a webhook to send requests when a user is deleted or a new ticket is created. You can manage webhooks usingAdmin Centeror theWebhooks API.
Connection methods
There are two ways to connect a webhook to activity in Zendesk Support:
订阅webhook Zendesk一个或多个事件亚博s. Use this connection method to send requests based on organization, user, help center, or community activity. For a list of supported event types, seeWebhook event typesin the API reference.
Connect the webhook to atriggerorautomation. Use this connection method to send requests based on ticket activity.
Important:A webhook that's subscribed to a Zendesk event can't connect to a trigger or automation. Similarly, a webhook that's connected to a trigger or automation can't subscribe to Zendesk events. You can’t change an existing webhook’s connection method.
Creating a webhook
To create a webhook using the API, make a request to theCreate or Clone Webhookendpoint. In the request body, specify the following parameters:
- A
namefor the webhook. The name doesn't need to be unique - A
statusindicating whether the webhook is "active" or "inactive" - An array of event
subscriptionsfor the webhook. To subscribe the webhook to Zendesk events, specify one or more event types. For supported event type values, seeWebhook event types. To connect the webhook to a trigger or automation, specify only "conditional_ticket_events" in the array. - An
endpointURL. The webhook sends requests to this URL - An
http_methodfor the webhook's requests. To subscribe the webhook to Zendesk events, this must be "POST" - A
request_formatfor the webhook's requests. To subscribe the webhook to Zendesk events, this must be "json"
Additionally, you can specify an optionalauthenticationparameter that adds API key, basic, or bearer authentication to the webhook's requests. For more information, seeWebhook security and authentication.
Optionally, if you're connecting to an HTTPS endpoint, you can add up to five custom headers to a webhook. Header names must be unique, can't exceed 128 characters, and support alphanumeric US ASCII characters and the following symbols:!,#,$,%,&,',*,+,-,.,^,`,_,|, and~. Header values can contain up to 1,000 characters and support alphanumeric US ASCII characters and the following symbols:!,",#,$,%,&,',(,),*,+,-,,,.,/,:,;,<,>,+,?,@,[,],\,^,`,_,{,},|, and~. White space is also supported in header values, although it can't be the first or last character.
Note:Don't include authentication credentials or other sensitive information in custom headers. Instead, use thesupported authentication methods.
The following request creates a webhook that's subscribed to two Zendesk events:User createdandOrganization created. The request'ssubscriptionsparameter is highlighted.
curl -X POST https://{subdomain}.zendesk.com/api/v2/webhooks \-u {email_address}:{password} \-H "Content-Type:application/json" \-d '{"webhook": {"name": "WEBHOOK_NAME","status": "active","endpoint": "DESTINATION_URL","http_method": "POST","request_format": "json","subscriptions": ["zen:event-type:user.created","zen:event-type:organization.created"],"authentication": {"type": "api_key","data": {"name": "HEADER_NAME"“价值”:“KEY_VALUE”},"add_position": "header"}"custom_headers": {"CUSTOM_HEADER_NAME": "VALUE"}}}'
The following request creates a webhook that can be connected to a trigger or automation.
curl -X POST https://{subdomain}.zendesk.com/api/v2/webhooks \-u {email_address}:{password} \-H "Content-Type:application/json" \-d '{"webhook": {"name": "WEBHOOK_NAME","status": "active","endpoint": "DESTINATION_URL","http_method": "POST","request_format": "json","subscriptions": ["conditional_ticket_events"],"authentication": {"type": "bearer_token","data": {"token": "TOKEN"},"add_position": "header"}}}'
If successful, the request's response contains a unique id for the webhook.
{"webhook":{"id":"01GD0NSM4FV0YVJ535XBA3X0XV","name":"WEBHOOK_NAME",...}}
Connecting a webhook to a trigger or automation
To connect a webhook to a trigger or automation, use the respectivetriggerorautomationactionsproperty's "notification_webhook" field. This field's value is an array of two strings specifying the webhook's id and the request's content.
For webhooks that use the POST, PUT, or PATCH HTTP method with a JSON or XML request format, the content is the request payload. The followingactionproperty adds a JSON request payload.
{"actions":[{"field":"notification_webhook","value":["123ABC","{\"foo\": \"bar\"}\n"]}]}
Webhooks using other HTTP methods or formats don't include a request payload. Instead, you can add custom URL parameters as an array of two key-value strings. For example, the followingactionproperty adds the?foo=bar&baz=quxURL parameters.
{"actions":[{"field":"notification_webhook","value":["123ABC",[["foo","bar"],["baz","qux"]]]}]}
For more information about theactionsproperty for trigger and automation objects, seeActions reference.
Cloning a webhook
To clone an existing webhook using the API, make aCreate or Clone Webhookrequest. In the request, use theclone_webhook_idURL parameter to specify a webhook to clone. Don't include a request body.
curl -X POST 'https://{subdomain}.zendesk.com/api/v2/webhooks?clone_webhook_id={webhook_id}' \-u {email_address}:{password}
A cloned webhook has a unique id but uses the samenameas the original webhook. You can specify a newnameusing anUpdate Webhookrequest. Cloned webhooks aren't connected to any triggers or automations upon creation.
Monitoring webhooks
An activity log captures all activity and the status of each invocation for each webhook in the last seven days.
GET /api/v2/webhooks/{webhook_id}/invocations/
You can filter the list in a variety of ways. For example, to see a record of all failed invocations in the last seven days, add the parameterfilter[status]to your request:
GET /api/v2/webhooks/{webhook_id}}/invocations?filter[status]=failed
Zendesk makes a best effort to deliver actions to webhooks a single time. However, we can't guarantee it. It is possible for a webhook to be invoked by the same action multiple times or, under certain circumstances such as thecircuit breakerbeing triggered, to not deliver an event at all. To detect duplicate invocations for a single event, usewebhook signatures. If duplicate invocations could cause a problem in your workflows, ensure actions resulting from your webhooks are idempotent.
Webhook retry logic
If the first attempt isn't successful, webhook invocations are retried up to three times if the server receiving the request returns an HTTP error code response of 409. Additionally, HTTP error code responses of 429 and 503 are retried if they contain aretry-afterheader with a value that is less than 60 seconds from the time the response is received. Webhook requests have a 10-second timeout; webhooks that time out are retried up to five times. Consecutive failed requests won't deactivate the webhook but could trigger thewebhook circuit breaker.
Each invocation of a webhook has a unique id that can be used to get detailed information about the attempts made for that invocation:
GET /api/v2/webhooks/{webhook_id}/invocations/{invocation_id}/attempts
Webhook circuit breaker
The webhook circuit breaker is designed to avoid bombarding broken endpoints with requests and is triggered under the following conditions:
- Within a five-minute period, 70% of a webhook's requests result in errors.
- A webhook receives more than 1,000 error responses within a five-minute period.
Note:The circuit breaker won't trigger if a webhook sends fewer than 100 requests within a five-minute period, regardless of the error rate.
When the circuit breaker triggers for a webhook, the webhook can't send requests for five seconds, even if an event or business rule would otherwise trigger it. After five seconds, the webhook can be triggered to send its request to the target endpoint. If that request receives an error response, the circuit breaker is triggered again for five seconds. This cycle continues until a successful request is sent, at which point the circuit breaker resets.
Each invocation attempt during the five-second circuit breaker pause is logged with a status ofcircuit broken.