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, or community 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.
78 comments
Jacob the Moderator
This announcement seems relevant to a lot of comments here:
Announcing API key authentication and custom headers for webhooks
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
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
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
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
Peter Hochstrasser
Hi
The syntax for the Token is /token, not /API
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 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
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
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
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
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 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
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
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
Jennie Grudi
Getting a 500 internal server error after testing
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
Jay Krishnan
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