| Suite | Team, Growth, Professional, Enterprise, or Enterprise Plus |
| Support | Team, Professional, or Enterprise |
Web developers typically use webhooks to invoke behavior in another system. For example, you can use webhooks to:
You must be an admin or an agent in a custom role with permission to create webhooks. Trial accounts are limited to a maximum of 10 webhooks and a rate limit of 60 invocations per minute.
About webhooks
There are two ways to connect a webhook to activity in Zendesk Support:
- Subscribe the webhook to one or more Zendesk events. Use this connection method to send requests based on organization, user, agent availability, help center, community, ticket, or messaging activity. For a list of supported event types, see Webhook event types in the API reference.
- Connect the webhook to a trigger or automation. Use this connection method to send requests based on ticket activity.
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.
Subscribing to Zendesk events
A webhook that's subscribed to one or more Zendesk events always sends requests using the POST HTTP method. The request includes a JSON payload that contains the event's data. You can't change the HTTP method or the payload for the request. For more information about event payload schemas, see Webhook event types in the API reference.
Connecting to triggers or automations
-
JSON
-
XML
-
Form-encoded content
You define the request's content when you connect the webhook to a trigger or automation. For webhooks that use the POST, PUT, or PATCH HTTP method with a JSON or XML request format, the content is the request payload. 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. When defining the request payload or URL parameters, you can use any of the available content placeholders to insert ticket data into the request.
The webhook's request payload or URL parameters must be less than 256 KB.
Webhook ordering and retries
When an event, trigger, or automation invokes a webhook, it queues the webhook job to be run but doesn't actually run the job immediately. Because webhook jobs are run independently, there is no guarantee that webhooks are executed in a particular order.
Webhook requests are automatically retried up to three times if the endpoint returns certain HTTP response codes. Unlike targets, consecutive failed requests won't deactivate webhooks. For more information and examples of retry scenarios, see Monitoring webhooks in our developer documentation.
Creating a webhook
You can create a webhook in Admin Center.
To create a webhook
- In Admin Center, click
Apps and integrations in the sidebar, then select Actions and webhooks > Webhooks. - Click Create webhook.
- To subscribe the webhook to one or more Zendesk events, select Zendesk events and select one or more event types from the dropdown.
- To connect the webhook to a trigger or automation, select Trigger or Automation.
- Click Next.
- Enter a Name and Description for the webhook.
- Enter the Endpoint URL that is used to integrate with the third-party service or system. See Webhook endpoints.
When setting up a webhook to integrate with a third party, you may need to consult the third party's documentation.
- Select the webhook's Request method and Request format.
- Select the Authentication method for the webhook and provide any additional information required. See Authenticating your webhook.
- (Optional) Click Add header to add a custom header, and then enter a Header name and Value. To add up to four more headers, click Add another header. See Custom webhook headers.
Note: Don't put sensitive information in your custom headers.
- (Optional) Click Test webhook to ensure it's working as expected.
- Click Create webhook to create the webhook.
- For trigger and automation webhooks, you must connect the webhook to a trigger or automation. See Connect the webhook to a Support trigger or automation. After connecting the trigger or automation, return to the Create webhook page and click Finish setup.
After you've created the webhook, you can view its details, subscriptions, and activity from the Webhooks page in Admin Center. See Managing webhooks.
Webhook endpoints
Webhooks send requests to the endpoint URL that you specify when creating them. The endpoint URL uses the following format: https://www.yourdomain.com/path.
Although it isn't required, the use of secure HTTP (HTTPS) is recommended. By providing a secure endpoint URL, you can enable authentication and pass data safely.
Custom webhook headers
Custom headers provide a way to include additional information in the request your webhook sends and can make it easier to connect to some third-party services that have unique webhook header requirements. Note the following requirements and limitations for custom headers:
- To use custom headers, you must use a secure (HTTPS) endpoint URL.
- Don't include authentication credentials or other sensitive information in custom headers. Instead, use the supported authentication methods.
- Header names must be unique and can't have more than 128 characters. All alphanumeric US ASCII characters are supported, as well as the following symbols:
!,#,$,%,&,',*,+,-,.,^,_,`,|, and~. - Header values can be up to 1,000 characters in length and support all US ASCII characters from 0x20 to 0x7E.
- The following headers aren't supported:
- 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
- Additionally, headers can't start with the following prefixes:
- access-control
- x-amzn
- x-apigw
- x-datadog
- x-envoy
- x-forwarded
- x-zendesk
Authenticating a webhook
If your webhook is integrating with a secure endpoint, you have three options for authenticating the webhook and the data it sends. You may want to reference third-party documentation about your endpoint's authentication requirements or work with a developer on your team to determine the correct authentication method for your webhook.
- None required: No authentication is configured or required.
- API key: Use an API key to authenticate the webhook.
- Basic authentication: Use a username and password to authenticate the webhook.
- Bearer token: Use an OAuth access token to authenticate the webhook.
If your developers want more information about webhook authentication, see Webhook security and authentication.
For additional security, you can also verify the webhook's signature. For more informaiton, see Verifying webhook authenticity.
Connect a webhook to a trigger or automation
To invoke a trigger and automation webhook, you must first connect it to a trigger or automation. The triggers and automations specify the circumstances under which the webhook should be invoked.
To connect a webhook to a Support trigger
- In Admin Center, click
Objects and rules in the sidebar, then select Business rules > Triggers. -
Create a new trigger or edit an existing one by hovering your mouse pointer over the options icon (
) and clicking Edit. - Under Actions, click Add action. Select Notify webhook and then select your webhook.
- Enter the webhook's request payload or URL parameters, depending on the webhook's request format. The payload or parameters must be less than 256 KB.
- Click Save.
- In Admin Center, click Objects and rules in the sidebar, then select Business rules > Automations.
-
Create a new automation or edit an existing one by hovering your mouse pointer over the options icon () and clicking Edit.
- Under Perform these actions, click the add action icon (
). Select Notifications: Notify webhook and then select your webhook. - Enter the webhook's request payload or URL parameters, depending on the webhook's request format. The payload or parameters must be less than 256 KB.
- Click Submit.
Testing a webhook
In Admin Center, you have the option to test the webhook with different event sources as well as requests. In addition to accessing existing webhooks specifically for testing, you can also test the webhook during creation or editing.
To test a webhook
- In Admin Center, click Apps and integrations in the sidebar, then select Actions and webhooks > Webhooks.
- Find the webhook in the list, click the options menu icon () on the webhook's row, and then click Test webhook.
- In the Test webhook panel, select an event to test. This is a sample request that you can use to test your endpoint URL.
- Enter the details of your test request—request body, parameters, or headers.
- Click Send test. The response is visible in the panel below your test request.
81 comments
Maik Künnemann
If I use a webhook with a ticket id placeholder inside the url, the activity log dont show any information about the used url. So I don't know anything about the request if the body was empty. Could you please add the request url to the activity log information?
0
Jacob the Moderator
Hi Prakash,
What is the error you're seeing?
Could be a number of things, are you authenticating the call?
https://support.zendesk.com/hc/en-us/articles/4408839108378?page=2#topic_qbn_v4w_dpb
0
prakash.sati
Hi All,
i am trying to create a webhook with end point url as https://yoursubdomain.zendesk.com/api/v2/tickets/{{ticket.id}}.json (i replaced your domain with our subdomain) however it returns with an error
If someone can help please!
0
Dane
There's no documented limit for the number of web-hooks you can created. However, it is advisable to always check the API rate limit of the web-hooks that will be utilized. For Zendesk API rate limits, please refer to Usage Limits.
@Julien,
The only natively available option is to see the status of each call. You can go to each web-hook and click the activity tab.
0
Julien MCC
Is there a way to handle status codes, like 4xx or 5xx responses ?
0
Venkata Subba
Webhooks targets - What max no of webhooks are allowed in LIVE?
0
Alex C
Dave Dyson thank you! That article provides the placeholders I needed (I used ticket.assignee.id for my purposes). I continue unable to update the tickets with the update-many endpoint. However, it all works with the tickets/{ticket.id} endpoint. The problem is it replaces all ticket tags with the one we're adding, which is what I did not want to do. So I'll continue messing around with this, but REALLY appreciate the correct placeholder article!
0
Dave Dyson
For the assignee id, you'd use /1263082116169 (see Zendesk Support placeholders reference for more info on placeholders). However, there isn't a placeholder that simply provides "good" or "bad" as text (there is one that would provide "Good, I am satisfied" (for example), but I think that would be more than you're looking for. As a workaround, you could create two copies of this trigger, one for Good (and Good with comment) ratings, and another for Bad/Bad with comment ratings, and hardcode "good" or "bad" into the string yourself.
Although I hear your trigger/webhook combo is working, I do have to provide the caveat that updating triggers this way can be unreliable: see Can I use a trigger and a webhook to update tickets?
1
Alex C
Hi, hoping someone can help me here. I'm looking for the appropriate placeholders for {{assignee_id}} and {{satisfaction_rating}} for a json trigger that is notifying an active webhook (that is known to be working).
The end goal is to add a tag to the ticket made up of the agent's ID+rating, so if a ticket is rated several times, we can capture what rating goes to each agent, versus automatically assigning the satisfaction rating of the ticket to the last agent that touched it.
The json I'm using (that is not working -.-) is:
{
"ticket": {
"additional_tags": ["csat_{{assignee_id}}_{{satisfaction_rating}}"],
"id": "{{ticket.id}}"
}
}
The tag I'd want added is something like csat_1234355_bad
As you can see, it's not catching the placeholders, only adding the csat and underscores. And second issue would be that it's not adding it to tags. I don't know if it won't add it because it knows the tag created is not what was requested, so it doesn't send it over to the ticket, but I'd be surprised if it did do that.
Note: I was able to use a similar json and trigger with the same webhook to add assignee name to a text field when the ticket changes group (to track number of escalations per agents), but using the placeholder {{current_user.email}}. In all the documentation I find, I can't find that placeholder (I keep using variations of that placeholder because it works, but can't recall where it came from initially). I don't know what the assignee ID and ticket rating counterparts of that placeholder would be. Does anyone know? Any help would be appreciated!
I've seen these articles:
Edit: Just found that "additional_tags" is for the endpoint "tickets/update_many.json", and the webhook i'm currently using has endpoint "tickets/{{ticket.id}}". So that might be the issue, haven't created new webhook yet....but still don't know the right placeholders.
0
Ronald
@Timothy Schauder
You are my hero! Thank you for providing the format for basic auth with token to Zendesk's own API. This was driving me crazy trying to figure this out!
0
Sign in to leave a comment.