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.
77 comments
Jacob the Moderator
Very exciting stuff!
Testing this I was expecting to see an event in the ticket event log, for tickets where a trigger ran a webhook action, but it isn't. Is this deliberate?
0
Jacquelyn Brewer
Hi Jacob. Thanks for your question. This is expected. Webhooks run in response to something else happening, such as a ticket event. The event that triggers the webhook to run might be captured in the ticket event log, but all of the webhook logging is captured in the webhook activity logs.
0
Jacob the Moderator
Thanks Jacquelyn. I get that the webhook specific logging is captured in the webhook activity logs, but since a trigger is firing on a ticket event, I would expect to see that action logged on said ticket - like any other trigger would.
2
Chris Hynes
How do we reference the contextual ticket ID in the URL?
With Targets, we are able to reference a ticket like this:
https://ourdomain.zendesk.com/api/v2/tickets/{{ticket.id}}.json
Which allows our automations to make updates to tickets. I don't see how to do this with the webhook model.
9
Peter Hochstrasser
@...
Seconded...
It looks as if the webhook URL is static at the moment.
This would require to rewrite all these targets into applications using a third party server or create Zendesk Apps to serve the purpose.
1
Nathan Gutauckas
@...
We are also using this same model to update tickets.
Our use case: Each user has a custom field: "CC Email". When a ticket is created by that user, that add that CC to the ticket's email CCs. (ie. add your manager to your tickets)
Right now our layout is: Trigger activates on update of ticket using JSON (PUT to email_ccs).
Trigger notifies HTTPs target https://ourdomain.zendesk.com/api/v2/tickets/{{ticket.id}}.json to update the ticket.
Looking to see how we can achieve this with webhooks. Thanks!
2
Jason Brown
I had the same question as Chris. I found that I could use the Update Many API endpoint and just pass a single ticket id. Placeholders are used in the Trigger JSON to set ticket ID.
1
Maik Künnemann
@... we use this targets, how can we do this with webhooks?
/api/v2/tickets/{{ticket.id}}.json
/api/v2/tickets/{{ticket.id}}/comments/{{ticket.latest_comment.id}}/make_private
3
Amber
Is there a plan to enable the use of placeholders in the Endpoint URL before HTTP targets are deprecated?
0
Peter Hochstrasser
@..., @...
Have a look at this article, and my comment:
https://support.zendesk.com/hc/en-us/articles/1260803041889?page=2#comment_4404887963418
BR, P.
0
Chris Hronek
In the "Testing a webhook" section is step 4 implying that we should be able to add request headers to the webhook? I don't see the option for creating headers in the webhook when I create it. Is this going to be an option?
1
Nathan Purcell
Is there a reference for the expected payload structure?
0
Peter Hochstrasser
Hi @...
As the webhooks will replace targets (at this time, only http targets), the payload is not defined in the webhook definition, but in the webhook execution in a trigger or automation.
In there, you can define the payload (as json).
0
Nathan Gutauckas
I was able to get my previous Trigger working by using the Update Many endpoint like @... mentioned.
For me, my end result looks like this:
Created new Webhook named Update Many Tickets with Endpoint "https://[domain].zendesk.com/api/v2/tickets/update_many", PUT (not POST), and JSON.
Trigger Action -> Notify active Webhook -> Update Many Tickets
JSON body:
After these changes everything seems to be working.
1
Rahmat Budiharso
Can I create custom request header for webhook?
2
Beau P.
Hello Rahmat,
Currently it is not possible do so, but there is an active discussion here that our product management team is monitoring. I'd recommend following and adding your use-case to this discussion as this helps guide future platform improvements! https://support.zendesk.com/hc/en-us/community/posts/115009370628-Passing-API-Header-in-HTTP-Target
Beau | Customer Advocate
Ask our Zendesk Community
0
Charles Larry
"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."
What are the "certain HTTP response codes"? Is this documented somewhere?
0
Chris Sos
Hi @...,
Yes, this is documented on Creating and monitoring webhooks on our developer documentation.
Chris
0
Bruno Cabral
I am also interested in the custom request header feature
0
Dave Dyson
Hi Bruno,
Head over to Passing API Header in HTTP Target, upvote that, and add your use case into the comments thread. The more information about what you'd need this for, the better. Thanks!
0
Carmelo Rigatuso
HI,
We're using a web hook to create a ticket in an internal system for certain types of support requests. In the activity log, I can see that there is a response from the internal system which contains an ID that I would love to be able to add to the Zendesk ticket. Is there any way to read each response and add it to a form field in a ticket?
1
Kevin Ford
Hi Carmelo Rigatuso,
Unless Zendesk adds some new functionality, the only way you're going to be able to populate a ticket field is to have your internal system use the Zendesk API to update the field outside of sending the response.
KF
0
Takkme
Hi,
I want to send ticket information to my notion database. So I'm try to make webhook but i can't make it because of the error saying
"{"object":"error","status":400,"code":"missing_version","message":"Notion-Version header failed validation: Notion-Version header should be defined, instead was `undefined`."}"
How can I add Notion-Version to the header of zendesk webhook??
0
Christopher Kennedy
At this time, it's not possible to supply custom headers when creating webhooks. Our Product Management team is considering additional authentication methods as a possible future feature enhancement. Feel free to share the details of your use case in a product feedback post. It can help us, as well as other users, gain insight into the problem you're looking to solve.
Best,
0
Dustin Swayne
Can you create a side conversation via a webhook?
Have tried the following with no success:
https://mydomain.zendesk.com/api/v2/tickets/{ticket_id}/side_conversations
and this in the trigger:
{
"message": {
"body": "I was trying to print an email when the printer suddenly started burning",
"from": {
"email": "myemail@something.com",
"name": "Johnny Agent"
},
"html_body": "I was trying to print an email when the printer suddenly started \u003cstrong\u003eburning\u003c/strong\u003e",
"preview_text": "I was trying to print an email when the printer suddenly",
"subject": "Help, my printer is on fire!",
"to": [
{
"email": "bob@example.com",
"name": "bob"
}
]
}
}
0
Dustin Swayne
I figured it out I was using the wrong placeholder in the endpoint url. It should be {{ticket.id}}
2
GS Admin
Hi ,
i am able to add private comments on tickets using target url and triggers , but when i try to use the similar login for webhook , only the tags are getting added from trigger but comment is not getting added , so could anyone please help :
trigger :
1
Dane
Try to modify your webhook URL similar to the one below. And use JSON for the comment body.
2
Peter Hochstrasser
Hi all
Do webhooks support basic auth with tokens, i.e. adding /token to the name and specify a token generated in Admin Center, Apps and Integrations, APIs, Zendesk API, Settings, instead of a password?
1
Timothy Schauder
Peter Hochstrasser, yes it appears that you can use the /token authentication by setting basic authentication and using the format below.
User: email@site.com/token
Password: [Token]
This actually addressed an issue I was having, so thanks for asking.
3