Creating and monitoring 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. You can manage webhooks using Admin Center or the Webhooks API.

Connection methods

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.

Important: 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.

Creating a webhook

To create a webhook using the API, make a request to the Create or Clone Webhook endpoint. In the request body, specify the following parameters:

• A name for the webhook. The name doesn't need to be unique
• A status indicating whether the webhook is "active" or "inactive"
• An array of event subscriptions for the webhook. To subscribe the webhook to Zendesk events, specify one or more event types. For supported event type values, see Webhook event types. To connect the webhook to a trigger or automation, specify only "conditional_ticket_events" in the array.
• An endpoint URL. The webhook sends requests to this URL
• An http_method for the webhook's requests. To subscribe the webhook to Zendesk events, this must be "POST"
• A request_format for the webhook's requests. To subscribe the webhook to Zendesk events, this must be "json"

Additionally, you can specify an optional authentication parameter that adds API key, basic, or bearer authentication to the webhook's requests. For more information, see Webhook security and authentication.

Optionally, if you're connecting to an HTTPS endpoint, you can add up to five custom headers to a webhook. Header names must be unique, can't exceed 128 characters, and support alphanumeric US ASCII characters and the following symbols: !, #, $, %, &, ', *, +, -, ., ^, `, _, |, and ~. Header values can contain up to 1,000 characters and support alphanumeric US ASCII characters and the following symbols: !, ", #, $, %, &, ', (, ), *, +, -, ,, ., /, :, ;, <, >, +, ?, @, [, ], \, ^, `, _, {, }, |, and ~. White space is also supported in header values, although it can't be the first or last character. For a complete list of unsupported custom headers, see Custom webhook headers.

Note: Don't include authentication credentials or other sensitive information in custom headers. Instead, use the supported authentication methods.

The following request creates a webhook that's subscribed to two Zendesk events: User created and Organization created. The request's subscriptions parameter is highlighted.

curl -X POST https://{subdomain}.zendesk.com/api/v2/webhooks \
  -u {email_address}/token:{api_token} \
  -H "Content-Type:application/json" \
  -d '{
    "webhook": {
      "name": "WEBHOOK_NAME",
      "status": "active",
      "endpoint": "DESTINATION_URL",
      "http_method": "POST",
      "request_format": "json",
      "subscriptions": [
        "zen:event-type:user.created",
        "zen:event-type:organization.created"
      ],
      "authentication": {
        "type": "api_key",
        "data": {
          "name": "HEADER_NAME"
          "value": "KEY_VALUE"
        },
        "add_position": "header"
      }
      "custom_headers": {
        "CUSTOM_HEADER_NAME": "VALUE"
      }
    }
  }'

The following request creates a webhook that can be connected to a trigger or automation.

curl -X POST https://{subdomain}.zendesk.com/api/v2/webhooks \
  -u {email_address}/token:{api_token} \
  -H "Content-Type:application/json" \
  -d '{
    "webhook": {
      "name": "WEBHOOK_NAME",
      "status": "active",
      "endpoint": "DESTINATION_URL",
      "http_method": "POST",
      "request_format": "json",
      "subscriptions": [
        "conditional_ticket_events"
      ],
      "authentication": {
        "type": "bearer_token",
        "data": {
          "token": "TOKEN"
        },
        "add_position": "header"
      }
    }
  }'

If successful, the request's response contains a unique id for the webhook.

{
  "webhook": {
    "id": "01GD0NSM4FV0YVJ535XBA3X0XV",
    "name": "WEBHOOK_NAME",
    ...
  }
}

Connecting a webhook to a trigger or automation

To connect a webhook to a trigger or automation, use the respective trigger or automation actions property's "notification_webhook" field. This field's value is an array of two strings specifying the webhook's id and the request's content.

For webhooks that use the POST, PUT, or PATCH HTTP method with a JSON or XML request format, the content is the request payload. The following action property adds a JSON request payload.

{
  "actions": [
    {
      "field": "notification_webhook",
      "value": ["123ABC", "{\"foo\": \"bar\"}\n"]
    }
  ]
}

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. For example, the following action property adds the ?foo=bar&baz=qux URL parameters.

{
  "actions": [
    {
      "field": "notification_webhook",
      "value": [
        "123ABC",
        [
          ["foo", "bar"],
          ["baz", "qux"]
        ]
      ]
    }
  ]
}

For more information about the actions property for trigger and automation objects, see Actions reference.

Cloning a webhook

To clone an existing webhook using the API, make a Create or Clone Webhook request. In the request, use the clone_webhook_id URL parameter to specify a webhook to clone. Don't include a request body.

curl -X POST 'https://{subdomain}.zendesk.com/api/v2/webhooks?clone_webhook_id={webhook_id}' \
  -u {email_address}/token:{api_token}

A cloned webhook has a unique id but uses the same name as the original webhook. You can specify a new name using an Update Webhook request. Cloned webhooks aren't connected to any triggers or automations upon creation.

Monitoring webhooks

An activity log captures all activity and the status of each invocation for each webhook in the last seven days.

GET /api/v2/webhooks/{webhook_id}/invocations/

You can filter the list in a variety of ways. For example, to see a record of all failed invocations in the last seven days, add the parameter filter[status] to your request:

GET /api/v2/webhooks/{webhook_id}}/invocations?filter[status]=failed

Zendesk makes a best effort to deliver actions to webhooks a single time. However, we can't guarantee it. It is possible for a webhook to be invoked by the same action multiple times or, under certain circumstances such as the circuit breaker being triggered, to not deliver an event at all. To detect duplicate invocations for a single event, use webhook signatures. If duplicate invocations could cause a problem in your workflows, ensure actions resulting from your webhooks are idempotent.

Webhook retry logic

If the first attempt isn't successful, webhook invocations are retried up to three times if the server receiving the request returns an HTTP error code response of 409. Additionally, HTTP error code responses of 429 and 503 are retried if they contain a retry-after header with a value that is less than 60 seconds from the time the response is received. Webhook requests have a 12-second timeout; webhooks that time out are retried up to five times. Consecutive failed requests won't deactivate the webhook but could trigger the webhook circuit breaker.

Each invocation of a webhook has a unique id that can be used to get detailed information about the attempts made for that invocation:

GET /api/v2/webhooks/{webhook_id}/invocations/{invocation_id}/attempts

Webhook circuit breaker

The webhook circuit breaker is designed to avoid bombarding broken endpoints with requests and is triggered under the following conditions:

• Within a five-minute period, 70% of a webhook's requests result in errors.
• A webhook receives more than 1,000 error responses within a five-minute period.

Note: The circuit breaker won't trigger if a webhook sends fewer than 100 requests within a five-minute period, regardless of the error rate.

When the circuit breaker triggers for a webhook, the webhook can't send requests for five seconds, even if an event or business rule would otherwise trigger it. After five seconds, the webhook can be triggered to send its request to the target endpoint. If that request receives an error response, the circuit breaker is triggered again for five seconds. This cycle continues until a successful request is sent, at which point the circuit breaker resets.

Each invocation attempt during the five-second circuit breaker pause is logged with a status of circuit broken.