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.
41 Comments
What can I do with the Webhook Response Body that is returned? Can I access it from within a trigger? Or does that have to be done in code?
@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!
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.
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?
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!
Webhooks targets - What max no of webhooks are allowed in LIVE?
Is there a way to handle status codes, like 4xx or 5xx responses ?
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.
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!
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
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?
Please sign in to leave a comment.