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 acustom rolewith 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, 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.
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, seeWebhook event typesin 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's payload or URL parameters, you can use any of theavailable content placeholdersto insert ticket data into the request.
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, seeMonitoring webhooksin our developer documentation.
Creating a webhook
You can create a webhook in Admin Center.
To create a webhook
- InAdmin Center, click
Apps and integrationsin the sidebar, then selectWebhooks > Webhooks. - ClickCreate webhook.
- To subscribe the webhook to one or more Zendesk events, selectZendesk eventsand select one or more event types from the dropdown.
- To connect the webhook to a trigger or automation, selectTrigger or Automation.
- ClickNext.
- Enter aNameandDescriptionfor the webhook.
- Enter theEndpoint URLthat is used to integrate with the third-party service or system. SeeWebhook 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'sRequest methodandRequest format.
- Select theAuthenticationmethod for the webhook and provide any additional information required. SeeAuthenticating your webhook.
- (Optional) ClickAdd headerto add a custom header, and then enter aHeader nameandValue. To add up to four more headers, clickAdd another header. SeeCustom webhook headers.Note:Don't put sensitive information in your custom headers.
- (Optional) ClickTest webhookto ensure it's working as expected.
- ClickCreate webhookto create the webhook.
- For trigger and automation webhooks, you must connect the webhook to a trigger or automation. SeeConnect the webhook to a Support trigger or automation. After connecting the trigger or automation, return to theCreate webhookpage and clickFinish setup.
After you've created the webhook, you can view its details, subscriptions, and activity from the Webhooks page in Admin Center. SeeManaging 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 canenable authenticationand 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 supportedauthentication 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.
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, seeWebhook security and authentication.
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
- InAdmin Center, click
对象一个d rulesin the sidebar, then selectBusiness rules > Triggers. - Create a new triggeror edit an existing one by hovering your mouse pointer over the options icon (
) and clickingEdit. - For triggers, underActions, clickAdd action. SelectNotify webhookand then select your webhook. ClickSave.
- InAdmin Center, click对象一个d rulesin the sidebar, then selectBusiness rules > Automations.
- Create a new automationor edit an existing one by hovering your mouse pointer over the options icon () and clickingEdit.
- 下的自动化,Perform these actions, click the add action icon (
). SelectNotifications: Notify webhookand then select your webhook. ClickSubmit.
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
- InAdmin Center, clickApps and integrationsin the sidebar, then selectWebhooks > Webhooks.
- Find the webhook in the list, click the options menu icon () on the webhook's row, and then clickTest webhook.
- In theTest webhookpanel, 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.
- ClickSend test. The response is visible in the panel below your test request.
61 Comments
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?
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 thewebhook activity logs.
Thanks Jacquelyn. I get that the webhook specific logging is captured in thewebhook 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.
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.
@...
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.
@...
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 targethttps://ourdomain.zendesk.com/api/v2/tickets/{{ticket.id}}.jsonto update the ticket.
Looking to see how we can achieve this with webhooks. Thanks!
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.
@...we use this targets, how can we do this with webhooks?
/api/v2/tickets/{{ticket.id}}.json
/ api / v2 /票/ {{ticket.id}} /评论/ {{ticket.latest_comment.id}}/make_private
Is there a plan to enable the use of placeholders in the Endpoint URL before HTTP targets are deprecated?
@...,@...
Have a look at this article, and my comment:
https://support.zendesk.com/hc/en-us/articles/1260803041889?page=2#comment_4404887963418
BR, P.
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?
Is there a reference for the expected payload structure?
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).
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:
创造了新的Webhook名叫更新许多门票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.
Can I create custom request header for webhook?
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 ourZendesk Community
"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?
Hi@...,
Yes, this is documented onCreating and monitoring webhookson our developer documentation.
Chris
I am also interested in the custom request header feature
Hi Bruno,
Head over toPassing 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!
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?
HiCarmelo 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
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??
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 aproduct feedback post. It can help us, as well as other users, gain insight into the problem you're looking to solve.
Best,
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"
}
]
}
}
I figured it out I was using the wrong placeholder in the endpoint url. It should be {{ticket.id}}
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 :
Try to modify your webhook URL similar to the one below. And use JSON for the comment body.
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?
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.
Pleasesign into leave a comment.