Creating webhooks

Fastpath: Admin Center > Apps and integrations > Webhooks > Webhooks

A webhook sends an HTTP request to a specified URL in response to activity in Zendesk Support. For example, you can configure a webhook to send requests when a user is deleted or a new ticket is created.

Web developers typically use webhooks to invoke behavior in another system. For example, you can use webhooks to:

• Alert your team in Slack when an urgent ticket is created
• Pass ticket details to your docs team in Asana after a ticket is resolved
• Notify your own back-end service about an important ticket event

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.

This article covers the following topics:

• About webhooks
• Creating a webhook
• Testing a webhook

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 or user 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

If a webhook is connected to a trigger or automation, you can customize the HTTP method, format, and content of the webhook's requests. You select the HTTP method and request body format when you create the webhook. Webhooks connected to a trigger or automation support the following request body formats:

• 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 the available content placeholders to 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, see Monitoring webhooks in our developer documentation.

Creating a webhook

You can create a webhook in Admin Center.

To create a webhook

1. In Admin Center, click Apps and integrations in the sidebar, then select Webhooks > Webhooks.
2. 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.
3. Click Next.
4. Select the webhook's connection method.
5. Configure the webhook to integrate with the third-party service or system. For more information, see Webhook endpoints and Authenticating your webhook.

   When setting up a webhook to integrate with a third party, you may need to consult their documentation.

6. (Optional) Click Test webhook to ensure it's working as expected.
7. Click Create webhook to create the webhook.
8. 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.

Authenticating your 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.
• 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.

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

1. In Admin Center, click Objects and rules in the sidebar, then select Business rules > Triggers.
2. Create a new trigger or edit an existing one by hovering your mouse pointer over the options icon () and clicking Edit.
3. For triggers, under Actions, click Add action. Select Notify webhook and then select your webhook. Click Save.

To connect a webhook to a Support automation

1. In Admin Center, click Objects and rules in the sidebar, then select Business rules > Automations.
2. Create a new automation or edit an existing one by hovering your mouse pointer over the options icon () and clicking Edit.
3. 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

1. In Admin Center, click Apps and integrations in the sidebar, then select Webhooks > Webhooks.
2. Find the webhook in the list, click the options menu icon () on the webhook's row, and then click Test webhook.
3. In the Test webhook panel, select an event to test. This is a sample request that you can use to test your endpoint URL.
4. Enter the details of your test request—request body, parameters, or headers.
5. Click Send test. The response is visible in the panel below your test request.