English (US)
  1. Zendesk help
  2. Apps and integrations
  3. Apps and integrations documentation
  4. Extending Zendesk

Creating webhooks to interact with third-party systems

Jacquelyn Brewer
  • Edited
Zendesk Documentation Team

What's my plan?

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

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, 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.

A best attempt is made to deliver webhook events for actions in Zendesk to users as near to real-time as possible, however, sometimes there is a delay.

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. Enter a Name and Description for the webhook.
  5. 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.

  6. Select the webhook's Request method and Request format.
  7. Select the Authentication method for the webhook and provide any additional information required. See Authenticating your webhook.
  8. (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.
  9. (Optional) Click Test webhook to ensure it's working as expected.
  10. Click Create webhook to create the webhook.
  11. 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.

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

  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.
Return to top

63 Comments

  • Jacob Christensen
    Community 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
    Zendesk Documentation Team

    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 Christensen
    Community 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:

    {
    "tickets": [
    { "id": "{{ticket.id}}",
    "email_ccs": [
    { "user_email": "{{ticket.requester.custom_fields.cc_email}}", "user_name": "{{ticket.requester.custom_fields.cc_email}}", "action": "put"}
    ]
    }
    ]
    }

    After these changes everything seems to be working.

    1
  • Rahmat Budiharso

    Can I create custom request header for webhook?

    2
  • Beau P.
    Zendesk Customer Care

    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
    Zendesk Product Manager

    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
    Community Moderator

    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
    Zendesk Developer Advocacy
    Hi Takkme,
     
    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
  • Texas Workforce Commission

    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
  • Texas Workforce Commission

    I figured it out I was using the wrong placeholder in the endpoint url. It should be {{ticket.id}}

    1
  • Gaurav Sharma

    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 :

    0
  • Dane
    Zendesk Engineering
    Hi Gaurav,
     
    Try to modify your webhook URL similar to the one below. And use JSON for the comment body.
     

     
     
    https://yoursubdomain.com/api/v2/tickets/{{ticket.id}}.json

{
  "ticket": {
    "comment": {
      "body": "Followup 1 Completed",
      "public": false
    }
  }
}
    1
  • Peter Hochstrasser
    • Edited

    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.

    2

Please sign in to leave a comment.

Powered by Zendesk