Webhooks

Webhooks

Webhooks are user-defined HTTP callbacks which create notifications by Zendesk events to destination systems. The Webhook API lets you manage webhooks and enable subscriptions to receive notifications about Zendesk events. You can use webhooks with triggers and automations to send a notification when a ticket is created or updated.

To specify a webhook notification as an action for a trigger or automation, use the action's notification_webhook field. This field's value is an array of two strings specifying the unique ID of the webhook and the message body. Example:

{
  "actions": [
    {
      "field": "notification_webhook",
      "value": [
        "01FMJQSY40HZBCBVPZB9212S8V",
        "Ticket {{ticket.id}} has been updated."
      ]
    }
  ]
}

For more information, see Triggers or Automations.

JSON Format

Webhooks are represented as JSON objects with the following properties:

Name	Type	Read-only	Mandatory	Description
authentication	object	false	false	Authentication data that enables the integration with the destination system. Supports basic authentication and bearer token authentication
created_at	string	true	false	When the webhook was created
created_by	string	true	false	The user id of the user who created the webhook. "-1" represents the Zendesk system
description	string	false	false	Webhook description
endpoint	string	false	true	The destination URL that the webhook notifies when Zendesk events occur
external_source	object	false	false	External source by which a webhook is created, e.g. Zendesk Marketplace
http_method	string	false	true	The HTTP method used by the webhook. Allowed values are "GET", "POST", "PUT", "PATCH", or "DELETE"
id	string	true	true	An auto-generated webhook id
name	string	false	true	Webhook name
request_format	string	false	true	The format of the data that the webhook will send. Allowed values are "json", "xml", or "form_encoded"
signing_secret	object	false	false	Signing secret which can be used for verifying request integrity
status	string	false	true	Current status of the webhook. Allowed values are "active" or "inactive"
subscriptions	array	false	false	Zendesk event subscriptions. Allowed value is "conditional_ticket_events"
updated_at	string	true	false	When the webhook was last updated
updated_by	string	true	false	The user id of the user who last updated the webhook

Example

{
  "created_at": "2020-10-20T08:16:28Z",
  "created_by": "1234567",
  "endpoint": "https://example.com/status/200",
  "http_method": "POST",
  "id": "01EJFTSCC78X5V07NPY2MHR00M",
  "name": "Example Webhook",
  "request_format": "json",
  "status": "active",
  "subscriptions": [
    "conditional_ticket_events"
  ],
  "updated_at": "2020-10-20T08:16:28Z",
  "updated_by": "1234567"
}

List Webhooks

• GET /api/v2/webhooks

Allowed For

• Agents

Parameters

Name	Type	In	Required	Description
filter[name_contains]	string	Query	false	Filters the webhooks by a string in the name
page[after]	string	Query	false	Includes the next page of results with defined size
page[before]	string	Query	false	Includes the previous page of results with defined size
page[size]	string	Query	false	Defines a specified number of results per page
sort	string	Query	false	Defines the sorting criteria. Only supports name and status. Allowed values are "name" or "status"

Using curl

curl https://{subdomain}.zendesk.com/api/v2/webhooks \
    -H 'Content-Type:application/json' \
    -v -u {email_address}:{password}

Example Response

Status 200 OK

{
  "links": {
    "next": "https://example.zendesk.com/api/v2/webhooks?page[size]=100\u0026page[after]=ijkl",
    "prev": "https://example.zendesk.com/api/v2/webhooks?page[size]=100\u0026page[before]=abcd"
  },
  "meta": {
    "after_cursor": "ijkl",
    "before_cursor": "abcd",
    "has_more": true
  },
  "webhooks": [
    {
      "created_at": "2020-10-20T08:16:28Z",
      "created_by": "1234567",
      "endpoint": "https://example.com/status/200",
      "http_method": "POST",
      "id": "01EJFTSCC78X5V07NPY2MHR00M",
      "name": "Example Webhook",
      "request_format": "json",
      "status": "active",
      "subscriptions": [
        "conditional_ticket_events"
      ],
      "updated_at": "2020-10-20T08:16:28Z",
      "updated_by": "1234567"
    }
  ]
}

Create or Clone Webhook

• POST /api/v2/webhooks

Creates or clones a webhook. The clone_webhook_id query parameter is only required when cloning a webhook. A request body is only required when creating a webhook.

Note that admins cannot clone webhooks created by Zendesk apps.

Allowed For

• Admins (external_source and signing_secret are not available to admins)

Parameters

Name	Type	In	Required	Description
clone_webhook_id	string	Query	false	The id of the webhook to be cloned. Only required if cloning a webhook

Example Body

{
  "webhook": {
    "authentication": {
      "add_position": "header",
      "data": {
        "password": "hello_123",
        "username": "john_smith"
      },
      "type": "basic_auth"
    },
    "endpoint": "https://example.com/status/200",
    "http_method": "GET",
    "name": "Example Webhook",
    "request_format": "json",
    "status": "active",
    "subscriptions": [
      "conditional_ticket_events"
    ]
  }
}

Using curl to create a webhook that does not use authentication

curl https://{subdomain}.zendesk.com/api/v2/webhooks \
  -d '{
    "webhook":{
      "endpoint":"{destination_endpoint_url}",
      "http_method":"POST",
      "name":"Test Webhook",
      "status":"active",
      "request_format":"json",
      "subscriptions":["conditional_ticket_events"]
    }
  }' \
  -H 'Content-Type:application/json' \
  -v -u {email_address}:{password} -X POST

Using curl to create a webhook that uses basic authentication

curl https://{subdomain}.zendesk.com/api/v2/webhooks \
  -d '{
    "webhook":{
      "endpoint":"{destination_endpoint_url}",
      "http_method":"POST",
      "name":"Test Webhook",
      "status":"active",
      "request_format":"json",
      "subscriptions":["conditional_ticket_events"],
      "authentication":{
        "type":"basic_auth",
        "data":{
            "username":"{username}",
            "password":"{password}"
        },
        "add_position":"header"
      }
    }
  }' \
  -H 'Content-Type:application/json' \
  -v -u {email_address}:{password} -X POST

Using curl to create a webhook that uses bearer token authentication

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

Using curl to clone an existing webhook

curl 'https://{subdomain}.zendesk.com/api/v2/webhooks?clone_webhook_id={webhook_id}' \
    -H 'Content-Type:application/json' \
    -v -u {email_address}:{password} -X POST

Example Response

Status 201 Created

{
  "webhook": {
    "authentication": {
      "add_position": "header",
      "type": "basic_auth"
    },
    "created_at": "2020-10-20T08:16:28Z",
    "created_by": "1234567",
    "endpoint": "https://example.com/status/200",
    "http_method": "POST",
    "id": "01EJFTSCC78X5V07NPY2MHR00M",
    "name": "Example Webhook",
    "request_format": "json",
    "status": "active",
    "subscriptions": [
      "conditional_ticket_events"
    ],
    "updated_at": "2020-10-20T08:16:28Z",
    "updated_by": "1234567"
  }
}

Test Webhook

• POST /api/v2/webhooks/test

Tests a new or existing webhook.

When testing an existing webhook, the existing webhook data will be attached automatically as part of the outbound test request. The data includes the request format, http method, authentication method (only if same type and add_position are attached), and signing secret. The request payload data will overwrite existing webhook data in the outbound test request.

Allowed For

• Admins

Parameters

Name	Type	In	Required	Description
webhook_id	string	Query	false	The webhook to be tested. Only required for testing an existing webhook

Example Body

{
  "request": {
    "endpoint": "https://example.com/status/200",
    "http_method": "POST",
    "payload": "{\"name\":\"test webhook\"}",
    "request_format": "json"
  }
}

Using curl to test a new webhook

curl https://{subdomain}.zendesk.com/api/v2/webhooks/test \
  -d '{
    "request":{
      "endpoint":"{destination_endpoint_url}",
      "http_method":"POST",
      "request_format":"json",
      "payload":"{\"say\":\"hello\"}"
    }
  }' \
  -H 'Content-Type:application/json' \
  -v -u {email_address}:{password} -X POST

Using curl to test an existing webhook that uses different authentication

curl 'https://{subdomain}.zendesk.com/api/v2/webhooks/test?webhook_id={existing_webhook_id}' \
  -d '{
    "request":{
      "endpoint":"{destination_endpoint_url}",
      "http_method":"POST",
      "request_format":"json",
      "authentication":{
        "type":"basic_auth",
        "data":{
          "username":"{username}",
          "password":"{password}"
        },
        "add_position":"header"
      },
      "payload":"{\"say\":\"hello\"}"
    }
  }' \
  -H 'Content-Type:application/json' \
  -v -u {email_address}:{password} -X POST

Using curl to test an existing webhook that uses existing authentication

curl 'https://{subdomain}.zendesk.com/api/v2/webhooks/test?webhook_id={existing_webhook_id}' \
  -d '{
    "request":{
      "endpoint":"{destination_endpoint_url}",
      "http_method":"POST",
      "request_format":"json",
      "authentication":{
        "type":"basic_auth",
        "add_position":"header"
      },
      "payload":"{\"say\":\"hello\"}"
    }
  }' \
  -H 'Content-Type:application/json' \
  -v -u {email_address}:{password} -X POST

Using curl to test an existing webhook without authentication

curl 'https://{subdomain}.zendesk.com/api/v2/webhooks/test?webhook_id={existing_webhook_id}' \
  -d '{
    "request":{
      "endpoint":"{destination_endpoint_url}",
      "http_method":"POST",
      "request_format":"json",
      "payload":"{\"say\":\"hello\"}"
    }
  }' \
  -H 'Content-Type:application/json' \
  -v -u {email_address}:{password} -X POST

Example Response

Status 200 OK

{
  "response": {
    "headers": [
      {
        "key": "Content-Type",
        "value": "application/json"
      }
    ],
    "payload": "{ \"success\": true }",
    "status": 200
  }
}

Show Webhook

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

Returns the specified webhook.

Allowed For

• Agents

Parameters

Name	Type	In	Required	Description
webhook_id	string	Path	true	Webhook Id

Using curl

curl https://{subdomain}.zendesk.com/api/v2/webhooks/{webhook_id} \
  -H 'Content-Type:application/json' \
  -v -u {email_address}:{password}

Example Response

Status 200 OK

{
  "webhook": {
    "authentication": {
      "add_position": "header",
      "type": "basic_auth"
    },
    "created_at": "2020-10-20T08:16:28Z",
    "created_by": "1234567",
    "endpoint": "https://example.com/status/200",
    "http_method": "POST",
    "id": "01EJFTSCC78X5V07NPY2MHR00M",
    "name": "Example Webhook",
    "request_format": "json",
    "status": "active",
    "subscriptions": [
      "conditional_ticket_events"
    ],
    "updated_at": "2020-10-20T08:16:28Z",
    "updated_by": "1234567"
  }
}

Update Webhook

• PUT /api/v2/webhooks/{webhook_id}

Updates the specified webhook.

Allowed For

• Admins (external_source and signing_secret are not available to admins)

Parameters

Name	Type	In	Required	Description
webhook_id	string	Path	true	Webhook id

Example Body

{
  "webhook": {
    "authentication": {
      "add_position": "header",
      "data": {
        "password": "hello_123",
        "username": "john_smith"
      },
      "type": "basic_auth"
    },
    "endpoint": "https://example.com/status/200",
    "http_method": "POST",
    "name": "Example Webhook",
    "request_format": "json",
    "status": "active",
    "subscriptions": [
      "conditional_ticket_events"
    ]
  }
}

Using curl to update webhook name

curl https://{subdomain}.zendesk.com/api/v2/webhooks/{webhook_id} \
  -d '{
      "webhook":{
        "name":"Updated Test Webhook",
        "status":"active",
        "subscriptions":[
          "conditional_ticket_events"
        ],
        "endpoint":"{destination_endpoint_url}",
        "http_method":"POST",
        "request_format":"json",
        "authentication":{
          "type":"basic_auth",
          "add_position":"header"
        }
      }
  }' \
  -H 'Content-Type:application/json' \
  -v -u {email_address}:{password} -X PUT

Using curl to update webhook basic authentication

curl https://{subdomain}.zendesk.com/api/v2/webhooks/{webhook_id} \
    -d '{
        "webhook":{
          "name":"Updated Test Webhook",
          "status":"active",
          "subscriptions":[
            "conditional_ticket_events"
          ],
          "endpoint":"{destination_endpoint_url}",
          "http_method":"POST",
          "request_format":"json",
          "authentication":{
            "type":"basic_auth",
            "data":{
                "username":"{username}",
                "password":"{password}"
            },
            "add_position":"header"
          }
        }
    }' \
  -H 'Content-Type:application/json' \
  -v -u {email_address}:{password} -X PUT

Using curl to update webhook bearer token authentication

curl https://{subdomain}.zendesk.com/api/v2/webhooks/{webhook_id} \
  -d '{
      "webhook":{
        "name":"Updated Test Webhook",
        "status":"active",
        "subscriptions":[
          "conditional_ticket_events"
        ],
        "endpoint":"{destination_endpoint_url}",
        "http_method":"POST",
        "request_format":"json",
        "authentication":{
          "type":"bearer_token",
          "data":{
              "token":"{token}"
          },
          "add_position":"header"
        }
      }
    }' \
  -H 'Content-Type:application/json' \
  -v -u {email_address}:{password} -X PUT

Using curl to update webhook and delete existing authentication

curl https://{subdomain}.zendesk.com/api/v2/webhooks/{webhook_id} \
  -d '{
      "webhook":{
        "name":"Updated Test Webhook",
        "status":"active",
        "subscriptions":[
          "conditional_ticket_events"
        ],
        "endpoint":"{destination_endpoint_url}",
        "http_method":"POST",
        "request_format":"json"
      }
  }' \
  -H 'Content-Type:application/json' \
  -v -u {email_address}:{password} -X PUT

Example Response

Status 204 No Content

Patch Webhook

• PATCH /api/v2/webhooks/{webhook_id}

Use the webhook_id to update a webhook. Note that patching only happens atomically at webhooks' top-level attributes.

Allowed For

• Admins (external_source and signing_secret are not available to admins)

Parameters

Name	Type	In	Required	Description
webhook_id	string	Path	true	Webhook Id

Example Body

{
  "webhook": {
    "name": "Updated Webhook Name"
  }
}

Using curl to patch webhook name

curl --location --request PATCH 'https://{subdomain}.zendesk.com/api/v2/webhooks/{webhook_id}' \
    --user '{email_address}:{password}' \
    --header 'Content-Type: application/merge-patch+json' \
    --data-raw '{
        "webhook": {
          "name": "Updated Test Webhook"
        }
      }'

Using curl to patch webhook basic authentication

curl --location --request PATCH 'https://{subdomain}.zendesk.com/api/v2/webhooks/{webhook_id}' \
    --user '{email_address}:{password}' \
    --header 'Content-Type: application/merge-patch+json' \
    --data-raw '{
        "webhook": {
          "authentication": {
            "type": "basic_auth",
            "data": {
              "username": "{username}",
              "password": "{password}"
            },
            "add_position": "header"
          }
        }
      }'

Using curl to patch webhook bearer token authentication

curl --location --request PATCH 'https://{subdomain}.zendesk.com/api/v2/webhooks/{webhook_id}' \
    --user '{email_address}:{password}' \
    --header 'Content-Type: application/merge-patch+json' \
    --data-raw '{
        "webhook": {
          "authentication": {
            "type": "bearer_token",
            "data": {
              "token": "{token}"
            },
            "add_position": "header"
          }
        }
      }'

Using curl to patch webhook and delete existing authentication

curl --location --request PATCH 'https://{subdomain}.zendesk.com/api/v2/webhooks/{webhook_id}' \
    --user '{email_address}:{password}' \
    --header 'Content-Type: application/merge-patch+json' \
    --data-raw '{
        "webhook": {
          "authentication": null
        }
      }'

Example Response

Status 204 No Content

Delete Webhook

• DELETE /api/v2/webhooks/{webhook_id}

Deletes the specified webhook.

Allowed For

• Admins

Parameters

Name	Type	In	Required	Description
webhook_id	string	Path	true	Webhook id

Using curl

curl https://{subdomain}.zendesk.com/api/v2/webhooks/{webhook_id} \
  -H 'Content-Type:application/json' \
  -v -u {email_address}:{password} -X DELETE

Example Response

Status 204 No Content

List Webhook Invocations

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

Returns up to 7 days of invocations for a webhook.

Allowed For

• Admins

Parameters

Name	Type	In	Required	Description
filter[from_ts]	string	Query	false	Filters invocations by from timestamp. Use ISO 8601 UTC format
filter[status]	string	Query	false	Filters invocations by invocation status. Allowed values are "unknown", "accepted", "success", "failed", "timeout", "circuit broken", "client error", or "server error"
filter[to_ts]	string	Query	false	Filters invocations by timestamp. Use ISO 8601 UTC format
page[after]	string	Query	false	Includes the next page of invocations with defined size
page[before]	string	Query	false	Includes the previous page of invocations with defined size
page[size]	string	Query	false	Defines a specific number of invocations per page
sort	string	Query	false	Defines a invocation attribute to sort invocations. Allowed values are "latest_completed_at", or "-latest_completed_at".
webhook_id	string	Path	true	Webhook id

Using curl

curl https://{subdomain}.zendesk.com/api/v2/webhooks/{webhook_id}/invocations \
  -H 'Content-Type:application/json' \
  -v -u {email_address}:{password}

Example Response

Status 200 OK

{
  "invocations": [
    {
      "id": "01EJQ864VDJPW855Y7KJ2NDX3J",
      "latest_completed_at": "2020-10-20T08:16:28Z",
      "status": "success",
      "status_code": 200
    }
  ],
  "links": {
    "next": "https://example.zendesk.com/api/v2/webhooks/01EWJEAEY7PC3F4NXXCK52FKAF/invocations?page[size]=100\u0026page[after]=ijkl",
    "prev": "https://example.zendesk.com/api/v2/webhooks/01EWJEAEY7PC3F4NXXCK52FKAF/invocations?page[size]=100\u0026page[before]=abcd"
  },
  "meta": {
    "after_cursor": "ijkl",
    "before_cursor": "abcd",
    "has_more": true
  }
}

List Webhook Invocation Attempts

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

Returns the invocation attempts for the specified webhook.

Allowed For

• Admins

Parameters

Name	Type	In	Required	Description
invocation_id	string	Path	true	Webhook invocation id
webhook_id	string	Path	true	Webhook id

Using curl

curl https://{subdomain}.zendesk.com/api/v2/webhooks/{webhook_id}/invocations/{invocation_id}/attempts \
  -H 'Content-Type:application/json' \
  -v -u {email_address}:{password}

Example Response

Status 200 OK

{
  "attempts": [
    {
      "completed_at": "2020-10-20T08:18:28Z",
      "id": "01FCWDBCPC91WW1J8CA95DA01N",
      "invocation_id": "01FCWDFMDY6BKG126MKMQRBWJV",
      "request": {
        "headers": [
          {
            "key": "User-Agent",
            "value": "Zendesk Webhook"
          },
          {
            "key": "Content-Type",
            "value": "application/json; charset=utf-8"
          },
          {
            "key": "X-Zendesk-Account-Id",
            "value": "123456"
          },
          {
            "key": "X-Zendesk-Webhook-Id",
            "value": "01FCWDBCPC91WW1J8CA95DA01N"
          },
          {
            "key": "X-Zendesk-Webhook-Invocation-Id",
            "value": "01FCWDFMDY6BKG126MKMQRBWJV"
          },
          {
            "key": "X-Zendesk-Webhook-Signature-Timestamp",
            "value": "2020-10-20T08:18:28Z"
          },
          {
            "key": "X-Zendesk-Webhook-Signature",
            "value": "sDIU2MSNd77r5Bdk+3dQns/TBVWjEsq7jT3QJXBmgjw="
          }
        ],
        "payload": {
          "ticket_id": "23",
          "ticket_title": "Ticket 23"
        }
      },
      "response": {
        "headers": [
          {
            "key": "Content-Type",
            "value": "application/json; charset=utf-8"
          },
          {
            "key": "Vary",
            "value": "Accept-Encoding"
          },
          {
            "key": "X-Request-Id",
            "value": "3c28d09e-2ed6-4e89-b904-eb6f3832fd04"
          }
        ],
        "payload": {
          "message": "Webhook notification is received"
        }
      },
      "status": "success",
      "status_code": 200
    }
  ]
}

Show Webhook Signing Secret

• GET /api/v2/webhooks/{webhook_id}/signing_secret

Returns the webhook's signing secret. Note that admins cannot reveal secrets of webhooks created by Zendesk apps.

Allowed For

• Admins

Parameters

Name	Type	In	Required	Description
webhook_id	string	Path	true	Webhook id

Using curl

curl https://{subdomain}.zendesk.com/api/v2/webhooks/{webhook_id}/signing_secret \
  -H 'Content-Type:application/json' \
  -v -u {email_address}:{password}

Example Response

Status 200 OK

{
  "signing_secret": {
    "algorithm": "SHA256",
    "secret": "dw8vJM1zyx3ZJRWUAEvUrULMS3IwjnMIO8ajtatR"
  }
}

Reset Webhook Signing Secret

• POST /api/v2/webhooks/{webhook_id}/signing_secret

Resets a signing secret for the specified webhook. Note that admins cannot reset secrets of webhooks created by Zendesk apps.

Allowed For

• Admins

Parameters

Name	Type	In	Required	Description
webhook_id	string	Path	true	Webhook id

Using curl

curl https://{subdomain}.zendesk.com/api/v2/webhooks/{webhook_id}/signing_secret \
  -H 'Content-Type:application/json' \
  -v -u {email_address}:{password} -X POST

Example Response

Status 201 Created

{
  "signing_secret": {
    "algorithm": "SHA256",
    "secret": "dw8vJM1zyx3ZJRWUAEvUrULMS3IwjnMIO8ajtatR"
  }
}

Webhooks In Trial Accounts

Zendesk accounts that are in a trial state are limited to creating 10 webhooks. If a webhook above this limit is attempted to be created, the following error will be returned:

Example Response

Status 403 Forbidden

{
  "errors": [
    {
      "code": "WebhookLimitExceeded",
      "title": "Webhook Limit Exceeded",
      "detail": "Account limit on number of webhooks has been reached"
    }
  ]
}