About webhooks
You can use webhooks to pass information to third-party services and REST APIs that accept JSON, XML, or form-encoded content in HTTP requests. You can also use webhooks to pass URL parameters to any URL.
Webhooks are used by automations and triggers in Zendesk Support when a ticket meets specified conditions. Webhooks are important because they are the means by which triggers and automations can result in actions based on the HTTP responses from third-party services.
You can use any of the available content placeholders to insert ticket data in the HTTP requests.
When a business rule fires a webhook, it queues the 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
To create a webhook
- In Admin Center, click
Apps and integrations in the sidebar, then select Webhooks > Webhooks.
- Click Actions and select Create webhook.
- Configure the webhook to integrate with the third-party service or system.
For more information, see Webhook endpoints and Authenticating your webhook.
- (Optional) Click Test webhook to ensure it's working as expected.
- Click Next to connect the webhook to a Support trigger or automation. This is done in the Zendesk Support admin interface.
- Return to the Create webhook page in Admin Center and click Finish setup.
After you've created a webhook and connected it to a trigger or automation, you can view the webhook's details, event subscriptions, and activity all from the Webhooks page in Admin Center. For more information, see Managing webhooks in Admin Center.
Webhook endpoints
Webhooks send requests and receive responses from the endpoint URL that you specify when creating them. This is how they integrate with third party services, APIs, and systems.
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 enable authentication and can pass data safely.
Authenticating your webhook
- None required - No authentication is configured or required.
- Basic authentication - Use a username and password to authenticate the webook.
- 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.
Connect a webhook to a trigger or automation
Before a webhook can do anything, it needs to be connected 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.
Note: If you're creating or editing a webhook, click Manage business rules. - Create a new trigger or edit an existing one by hovering your mouse pointer over the options icon (
) and clicking Edit.
- For triggers, under Actions, click Add action. Select Notify webhook and then select your webhook. Click Save.
- In Admin Center, click
Objects and rules in the sidebar, then select Business rules > Automations.
Note: If you're creating or editing a webhook, click Manage business rules. - Create a new automation or edit an existing one by hovering your mouse pointer over the options icon (
) and clicking Edit.
- For automations, under Perform these actions, click the add action icon (
). Select Notifications: Notify webhook and then select your webhook. 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 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 a Test event source. This is an attached trigger or a sample ticket 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.
38 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 the webhook activity logs.
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.
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 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!
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/tickets/{{ticket.id}}/comments/{{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:
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.
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 our Zendesk 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 on Creating and monitoring webhooks on our developer documentation.
Chris
I am also interested in the custom request header feature
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!
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?
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
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 a product 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.
Please sign in to leave a comment.