Webhooks API
A webhook sends an HTTP request to a specified URL in response to an 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.
For webhook connection methods and more information, see Creating and monitoring webhooks.
JSON format
Webhooks are represented as JSON objects with the following properties:
Name | Type | Read-only | Mandatory | Description |
---|---|---|---|---|
authentication | object | false | false | Adds authentication to the webhook's HTTP requests. See Webhook security and authentication |
created_at | string | true | false | When the webhook was created |
created_by | string | true | false | id of the user who created the webhook. "-1" represents the Zendesk system |
custom_headers | object | false | false | Custom headers to deliver additional non-credential info to destinations |
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 | HTTP method used for the webhook's requests. To subscribe the webhook to Zendesk events, this must be "POST". 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. To subscribe the webhook to Zendesk events, this must be "json". Allowed values are "json", "xml", or "form_encoded". |
signing_secret | object | false | false | Signing secret used to verify webhook requests. See Verifying webhook authenticity |
status | string | false | true | Current status of the webhook. Allowed values are "active", or "inactive". |
subscriptions | array | false | false | 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 |
updated_at | string | true | false | When the webhook was last updated |
updated_by | string | true | false | 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
List 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 |
filter[status] | string | Query | false | Filters the webhooks by webhook status. Allowed values are "active", or "inactive". |
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". |
Code Samples
curl
curl https://{subdomain}.zendesk.com/api/v2/webhooks \
-H 'Content-Type: application/json' \
-v -u {email_address}/token:{api_token}
Go
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://support.zendesk.com/api/v2/webhooks?filter[name_contains]=&filter[status]=&page[after]=&page[before]=&page[size]=&sort="
method := "GET"
req, err := http.NewRequest(method, url, nil)
if err != nil {
fmt.Println(err)
return
}
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
client := &http.Client {}
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := io.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
Java
import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/webhooks")
.newBuilder()
.addQueryParameter("filter[name_contains]", "")
.addQueryParameter("filter[status]", "")
.addQueryParameter("page[after]", "")
.addQueryParameter("page[before]", "")
.addQueryParameter("page[size]", "")
.addQueryParameter("sort", "");
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()
.url(urlBuilder.build())
.method("GET", null)
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", basicAuth)
.build();
Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {
method: 'GET',
url: 'https://support.zendesk.com/api/v2/webhooks',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
},
params: {
'filter[name_contains]': '',
'filter[status]': '',
'page[after]': '',
'page[before]': '',
'page[size]': '',
'sort': '',
},
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
Python
import requests
from requests.auth import HTTPBasicAuth
url = "https://support.zendesk.com/api/v2/webhooks?filter[name_contains]=&filter[status]=&page[after]=&page[before]=&page[size]=&sort="
headers = {
"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(
"GET",
url,
auth=auth,
headers=headers
)
print(response.text)
Ruby
require "net/http"
require "base64"
uri = URI("https://support.zendesk.com/api/v2/webhooks")
uri.query = URI.encode_www_form("filter[name_contains]": "", "filter[status]": "", "page[after]": "", "page[before]": "", "page[size]": "", "sort": "")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
http.request(request)
end
Example response(s)
200 OK
// Status 200 OK
{
"links": {
"next": "https://example.zendesk.com/api/v2/webhooks?page[size]=100&page[after]=ijkl",
"prev": "https://example.zendesk.com/api/v2/webhooks?page[size]=100&page[before]=abcd"
},
"meta": {
"after_cursor": "ijkl",
"before_cursor": "abcd",
"has_more": true
},
"webhooks": [
{
"authentication": {
"add_position": "header",
"data": {
"username": "example_username"
},
"type": "basic_auth"
},
"created_at": "2020-10-20T08:16:28Z",
"created_by": "1234567",
"custom_headers": {
"header-one": "value_one",
"header-two": "value_two"
},
"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, with restrictions on certain actions
Admins cannot set
external_source
andsigning_secret
when creating a webhook.
Webhooks for trial accounts
Zendesk trial accounts are limited to 10 webhooks. Attempts to exceed this limit return the following error:
Status 403 Forbidden
{
"errors": [
{
"code": "WebhookLimitExceeded",
"title": "Webhook Limit Exceeded",
"detail": "Account limit on number of webhooks has been reached"
}
]
}
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
clone_webhook_id | string | Query | false | id of the webhook to clone. Only required if cloning a webhook. |
Example body
{
"webhook": {
"authentication": {
"add_position": "header",
"data": {
"password": "hello_123",
"username": "john_smith"
},
"type": "basic_auth"
},
"custom_headers": {
"header-one": "value_one",
"header-two": "value_two"
},
"endpoint": "https://example.com/status/200",
"http_method": "GET",
"name": "Example Webhook",
"request_format": "json",
"status": "active",
"subscriptions": [
"conditional_ticket_events"
]
}
}
Code Samples
Curl
curl --request POST https://support.zendesk.com/api/v2/webhooks?clone_webhook_id= \
--header "Content-Type: application/json" \
-u {email_address}/token:{api_token} \
--data-raw '{
"webhook": {
"authentication": {
"add_position": "header",
"data": {
"password": "hello_123",
"username": "john_smith"
},
"type": "basic_auth"
},
"custom_headers": {
"header-one": "value_one",
"header-two": "value_two"
},
"endpoint": "https://example.com/status/200",
"http_method": "GET",
"name": "Example Webhook",
"request_format": "json",
"status": "active",
"subscriptions": [
"conditional_ticket_events"
]
}
}'
Go
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
url := "https://support.zendesk.com/api/v2/webhooks?clone_webhook_id="
method := "POST"
payload := strings.NewReader(`{
"webhook": {
"authentication": {
"add_position": "header",
"data": {
"password": "hello_123",
"username": "john_smith"
},
"type": "basic_auth"
},
"custom_headers": {
"header-one": "value_one",
"header-two": "value_two"
},
"endpoint": "https://example.com/status/200",
"http_method": "GET",
"name": "Example Webhook",
"request_format": "json",
"status": "active",
"subscriptions": [
"conditional_ticket_events"
]
}
}`)
req, err := http.NewRequest(method, url, payload)
if err != nil {
fmt.Println(err)
return
}
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
client := &http.Client {}
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := io.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
Java
import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/webhooks")
.newBuilder()
.addQueryParameter("clone_webhook_id", "");
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
"""
{
\"webhook\": {
\"authentication\": {
\"add_position\": \"header\",
\"data\": {
\"password\": \"hello_123\",
\"username\": \"john_smith\"
},
\"type\": \"basic_auth\"
},
\"custom_headers\": {
\"header-one\": \"value_one\",
\"header-two\": \"value_two\"
},
\"endpoint\": \"https://example.com/status/200\",
\"http_method\": \"GET\",
\"name\": \"Example Webhook\",
\"request_format\": \"json\",
\"status\": \"active\",
\"subscriptions\": [
\"conditional_ticket_events\"
]
}
}""");
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()
.url(urlBuilder.build())
.method("POST", body)
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", basicAuth)
.build();
Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var data = JSON.stringify({
"webhook": {
"authentication": {
"add_position": "header",
"data": {
"password": "hello_123",
"username": "john_smith"
},
"type": "basic_auth"
},
"custom_headers": {
"header-one": "value_one",
"header-two": "value_two"
},
"endpoint": "https://example.com/status/200",
"http_method": "GET",
"name": "Example Webhook",
"request_format": "json",
"status": "active",
"subscriptions": [
"conditional_ticket_events"
]
}
});
var config = {
method: 'POST',
url: 'https://support.zendesk.com/api/v2/webhooks',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
},
params: {
'clone_webhook_id': '',
},
data : data,
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
Python
import requests
import json
from requests.auth import HTTPBasicAuth
url = "https://support.zendesk.com/api/v2/webhooks?clone_webhook_id="
payload = json.loads("""{
"webhook": {
"authentication": {
"add_position": "header",
"data": {
"password": "hello_123",
"username": "john_smith"
},
"type": "basic_auth"
},
"custom_headers": {
"header-one": "value_one",
"header-two": "value_two"
},
"endpoint": "https://example.com/status/200",
"http_method": "GET",
"name": "Example Webhook",
"request_format": "json",
"status": "active",
"subscriptions": [
"conditional_ticket_events"
]
}
}""")
headers = {
"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(
"POST",
url,
auth=auth,
headers=headers,
json=payload
)
print(response.text)
Ruby
require "net/http"
require "base64"
uri = URI("https://support.zendesk.com/api/v2/webhooks")
uri.query = URI.encode_www_form("clone_webhook_id": "")
request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")
request.body = %q({
"webhook": {
"authentication": {
"add_position": "header",
"data": {
"password": "hello_123",
"username": "john_smith"
},
"type": "basic_auth"
},
"custom_headers": {
"header-one": "value_one",
"header-two": "value_two"
},
"endpoint": "https://example.com/status/200",
"http_method": "GET",
"name": "Example Webhook",
"request_format": "json",
"status": "active",
"subscriptions": [
"conditional_ticket_events"
]
}
})
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
http.request(request)
end
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}/token:{api_token} -X POST
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}/token:{api_token} -X POST
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}/token:{api_token} -X POST
curl to create a webhook that uses API key authentication and custom headers
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": "api_key",
"data": {
"name": "{header_name}",
"value": "{header_value}"
},
"add_position": "header"
},
"custom_headers": {
"header-one": "value_one",
"header-two": "value_two"
}
}
}' \
-H 'Content-Type: application/json' \
-v -u {email_address}/token:{api_token} -X POST
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}/token:{api_token} -X POST
Example response(s)
201 Created
// Status 201 Created
{
"webhook": {
"authentication": {
"add_position": "header",
"data": {
"username": "example_username"
},
"type": "basic_auth"
},
"created_at": "2020-10-20T08:16:28Z",
"created_by": "1234567",
"custom_headers": {
"header-one": "value_one",
"header-two": "value_two"
},
"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"
}
}
400 Bad Request
// Status 400 Bad Request
{
"errors": [
{
"code": "InvalidWebhookName",
"detail": "Webhook name is required",
"id": "6ef45d115c1cfe68-ORD",
"source": {
"pointer": "/webhook/name"
},
"title": "Invalid Webhook Name"
}
]
}
403 Forbidden
// Status 403 Forbidden
{
"errors": [
{
"code": "WebhookLimitExceeded",
"detail": "Account limit on number of webhooks has been reached",
"id": "6ef45d115c1cfe68-ORD",
"title": "Webhook Limit Exceeded"
}
]
}
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": {
"custom_headers": {
"header-one": "value_one",
"header-two": "value_two"
},
"endpoint": "https://example.com/status/200",
"http_method": "POST",
"payload": "{\"name\":\"test webhook\"}",
"request_format": "json"
}
}
Code Samples
Curl
curl --request POST https://support.zendesk.com/api/v2/webhooks/test?webhook_id= \
--header "Content-Type: application/json" \
-u {email_address}/token:{api_token} \
--data-raw '{
"request": {
"custom_headers": {
"header-one": "value_one",
"header-two": "value_two"
},
"endpoint": "https://example.com/status/200",
"http_method": "POST",
"payload": "{\"name\":\"test webhook\"}",
"request_format": "json"
}
}'
Go
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
url := "https://support.zendesk.com/api/v2/webhooks/test?webhook_id="
method := "POST"
payload := strings.NewReader(`{
"request": {
"custom_headers": {
"header-one": "value_one",
"header-two": "value_two"
},
"endpoint": "https://example.com/status/200",
"http_method": "POST",
"payload": "{\"name\":\"test webhook\"}",
"request_format": "json"
}
}`)
req, err := http.NewRequest(method, url, payload)
if err != nil {
fmt.Println(err)
return
}
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
client := &http.Client {}
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := io.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
Java
import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/webhooks/test")
.newBuilder()
.addQueryParameter("webhook_id", "");
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
"""
{
\"request\": {
\"custom_headers\": {
\"header-one\": \"value_one\",
\"header-two\": \"value_two\"
},
\"endpoint\": \"https://example.com/status/200\",
\"http_method\": \"POST\",
\"payload\": \"{\\"name\\":\\"test webhook\\"}\",
\"request_format\": \"json\"
}
}""");
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()
.url(urlBuilder.build())
.method("POST", body)
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", basicAuth)
.build();
Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var data = JSON.stringify({
"request": {
"custom_headers": {
"header-one": "value_one",
"header-two": "value_two"
},
"endpoint": "https://example.com/status/200",
"http_method": "POST",
"payload": "{\"name\":\"test webhook\"}",
"request_format": "json"
}
});
var config = {
method: 'POST',
url: 'https://support.zendesk.com/api/v2/webhooks/test',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
},
params: {
'webhook_id': '',
},
data : data,
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
Python
import requests
import json
from requests.auth import HTTPBasicAuth
url = "https://support.zendesk.com/api/v2/webhooks/test?webhook_id="
payload = json.loads("""{
"request": {
"custom_headers": {
"header-one": "value_one",
"header-two": "value_two"
},
"endpoint": "https://example.com/status/200",
"http_method": "POST",
"payload": "{\"name\":\"test webhook\"}",
"request_format": "json"
}
}""")
headers = {
"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(
"POST",
url,
auth=auth,
headers=headers,
json=payload
)
print(response.text)
Ruby
require "net/http"
require "base64"
uri = URI("https://support.zendesk.com/api/v2/webhooks/test")
uri.query = URI.encode_www_form("webhook_id": "")
request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")
request.body = %q({
"request": {
"custom_headers": {
"header-one": "value_one",
"header-two": "value_two"
},
"endpoint": "https://example.com/status/200",
"http_method": "POST",
"payload": "{\"name\":\"test webhook\"}",
"request_format": "json"
}
})
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
http.request(request)
end
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}/token:{api_token} -X POST
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}/token:{api_token} -X POST
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}/token:{api_token} -X POST
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}/token:{api_token} -X POST
Example response(s)
200 OK
// Status 200 OK
{
"response": {
"headers": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"payload": "{ \"success\": true }",
"status": 200
}
}
400 Bad Request
// Status 400 Bad Request
{
"errors": [
{
"code": "InvalidWebhookEndpoint",
"detail": "Webhook endpoint is required",
"id": "6ef45d115c1cfe68-ORD",
"source": {
"pointer": "/webhook/endpoint"
},
"title": "Invalid Webhook Endpoint"
}
]
}
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 |
Code Samples
curl
curl https://{subdomain}.zendesk.com/api/v2/webhooks/{webhook_id} \
-H 'Content-Type: application/json' \
-v -u {email_address}/token:{api_token}
Go
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://support.zendesk.com/api/v2/webhooks/"
method := "GET"
req, err := http.NewRequest(method, url, nil)
if err != nil {
fmt.Println(err)
return
}
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
client := &http.Client {}
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := io.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
Java
import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/webhooks/")
.newBuilder();
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()
.url(urlBuilder.build())
.method("GET", null)
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", basicAuth)
.build();
Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {
method: 'GET',
url: 'https://support.zendesk.com/api/v2/webhooks/',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
},
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
Python
import requests
from requests.auth import HTTPBasicAuth
url = "https://support.zendesk.com/api/v2/webhooks/"
headers = {
"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(
"GET",
url,
auth=auth,
headers=headers
)
print(response.text)
Ruby
require "net/http"
require "base64"
uri = URI("https://support.zendesk.com/api/v2/webhooks/")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
http.request(request)
end
Example response(s)
200 OK
// Status 200 OK
{
"webhook": {
"authentication": {
"add_position": "header",
"data": {
"username": "example_username"
},
"type": "basic_auth"
},
"created_at": "2020-10-20T08:16:28Z",
"created_by": "1234567",
"custom_headers": {
"header-one": "value_one",
"header-two": "value_two"
},
"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"
}
}
400 Bad Request
// Status 400 Bad Request
{
"errors": [
{
"code": "InvalidWebhookID",
"detail": "Webhook id is required",
"id": "6ef45d115c1cfe68-ORD",
"source": {
"pointer": "/webhook/id"
},
"title": "Invalid Webhook ID"
}
]
}
404 Not Found
// Status 404 Not Found
{
"errors": [
{
"code": "WebhookNotFound",
"detail": "Webhook 01EMRHACJ81KB01FZW30NE8SJ3 could not be found",
"id": "6ef45d115c1cfe68-ORD",
"title": "Webhook Not Found"
}
]
}
Update Webhook
PUT /api/v2/webhooks/{webhook_id}
Updates the specified webhook.
Allowed for
-
Admins, with restrictions on certain actions
Admins cannot set
external_source
andsigning_secret
when updating a webhook.
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"
},
"custom_headers": {
"header-one": "new_value_one",
"header-two": "new_value_two"
},
"endpoint": "https://example.com/status/200",
"http_method": "POST",
"name": "Example Webhook",
"request_format": "json",
"status": "active",
"subscriptions": [
"conditional_ticket_events"
]
}
}
Code Samples
Curl
curl --request PUT https://support.zendesk.com/api/v2/webhooks/ \
--header "Content-Type: application/json" \
-u {email_address}/token:{api_token} \
--data-raw '{
"webhook": {
"authentication": {
"add_position": "header",
"data": {
"password": "hello_123",
"username": "john_smith"
},
"type": "basic_auth"
},
"custom_headers": {
"header-one": "new_value_one",
"header-two": "new_value_two"
},
"endpoint": "https://example.com/status/200",
"http_method": "POST",
"name": "Example Webhook",
"request_format": "json",
"status": "active",
"subscriptions": [
"conditional_ticket_events"
]
}
}'
Go
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
url := "https://support.zendesk.com/api/v2/webhooks/"
method := "PUT"
payload := strings.NewReader(`{
"webhook": {
"authentication": {
"add_position": "header",
"data": {
"password": "hello_123",
"username": "john_smith"
},
"type": "basic_auth"
},
"custom_headers": {
"header-one": "new_value_one",
"header-two": "new_value_two"
},
"endpoint": "https://example.com/status/200",
"http_method": "POST",
"name": "Example Webhook",
"request_format": "json",
"status": "active",
"subscriptions": [
"conditional_ticket_events"
]
}
}`)
req, err := http.NewRequest(method, url, payload)
if err != nil {
fmt.Println(err)
return
}
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
client := &http.Client {}
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := io.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
Java
import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/webhooks/")
.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
"""
{
\"webhook\": {
\"authentication\": {
\"add_position\": \"header\",
\"data\": {
\"password\": \"hello_123\",
\"username\": \"john_smith\"
},
\"type\": \"basic_auth\"
},
\"custom_headers\": {
\"header-one\": \"new_value_one\",
\"header-two\": \"new_value_two\"
},
\"endpoint\": \"https://example.com/status/200\",
\"http_method\": \"POST\",
\"name\": \"Example Webhook\",
\"request_format\": \"json\",
\"status\": \"active\",
\"subscriptions\": [
\"conditional_ticket_events\"
]
}
}""");
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()
.url(urlBuilder.build())
.method("PUT", body)
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", basicAuth)
.build();
Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var data = JSON.stringify({
"webhook": {
"authentication": {
"add_position": "header",
"data": {
"password": "hello_123",
"username": "john_smith"
},
"type": "basic_auth"
},
"custom_headers": {
"header-one": "new_value_one",
"header-two": "new_value_two"
},
"endpoint": "https://example.com/status/200",
"http_method": "POST",
"name": "Example Webhook",
"request_format": "json",
"status": "active",
"subscriptions": [
"conditional_ticket_events"
]
}
});
var config = {
method: 'PUT',
url: 'https://support.zendesk.com/api/v2/webhooks/',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
},
data : data,
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
Python
import requests
import json
from requests.auth import HTTPBasicAuth
url = "https://support.zendesk.com/api/v2/webhooks/"
payload = json.loads("""{
"webhook": {
"authentication": {
"add_position": "header",
"data": {
"password": "hello_123",
"username": "john_smith"
},
"type": "basic_auth"
},
"custom_headers": {
"header-one": "new_value_one",
"header-two": "new_value_two"
},
"endpoint": "https://example.com/status/200",
"http_method": "POST",
"name": "Example Webhook",
"request_format": "json",
"status": "active",
"subscriptions": [
"conditional_ticket_events"
]
}
}""")
headers = {
"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(
"PUT",
url,
auth=auth,
headers=headers,
json=payload
)
print(response.text)
Ruby
require "net/http"
require "base64"
uri = URI("https://support.zendesk.com/api/v2/webhooks/")
request = Net::HTTP::Put.new(uri, "Content-Type": "application/json")
request.body = %q({
"webhook": {
"authentication": {
"add_position": "header",
"data": {
"password": "hello_123",
"username": "john_smith"
},
"type": "basic_auth"
},
"custom_headers": {
"header-one": "new_value_one",
"header-two": "new_value_two"
},
"endpoint": "https://example.com/status/200",
"http_method": "POST",
"name": "Example Webhook",
"request_format": "json",
"status": "active",
"subscriptions": [
"conditional_ticket_events"
]
}
})
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
http.request(request)
end
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}/token:{api_token} -X PUT
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}/token:{api_token} -X PUT
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}/token:{api_token} -X PUT
curl to update webhook API key authentication and replace all custom headers
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": "api_key",
"data": {
"name": "{header_name},
"value": "{header_value}"
},
"add_position": "header"
},
"custom_headers": {
"header-one": "new_value_one",
"header-two": "new_value_two"
}
}
}' \
-H 'Content-Type: application/json' \
-v -u {email_address}:{password} -X PUT
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(s)
204 No Content
// Status 204 No Content
null
400 Bad Request
// Status 400 Bad Request
{
"errors": [
{
"code": "InvalidWebhookID",
"detail": "Webhook id is required",
"id": "6ef45d115c1cfe68-ORD",
"source": {
"pointer": "/webhook/id"
},
"title": "Invalid Webhook ID"
}
]
}
404 Not Found
// Status 404 Not Found
{
"errors": [
{
"code": "WebhookNotFound",
"detail": "Webhook 01EMRHACJ81KB01FZW30NE8SJ3 could not be found",
"id": "6ef45d115c1cfe68-ORD",
"title": "Webhook Not Found"
}
]
}
Patch Webhook
PATCH /api/v2/webhooks/{webhook_id}
Use the webhook_id
to update a webhook.
Allowed for
-
Admins, with restrictions on certain actions
Admins cannot set
external_source
andsigning_secret
when patching a webhook.
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
webhook_id | string | Path | true | Webhook id |
Example body
{
"webhook": {
"name": "Updated Webhook Name"
}
}
Code Samples
Curl
curl --request PATCH https://support.zendesk.com/api/v2/webhooks/ \
--header "Content-Type: application/json" \
-u {email_address}/token:{api_token} \
--data-raw '{
"webhook": {
"name": "Updated Webhook Name"
}
}'
Go
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
url := "https://support.zendesk.com/api/v2/webhooks/"
method := "PATCH"
payload := strings.NewReader(`{
"webhook": {
"name": "Updated Webhook Name"
}
}`)
req, err := http.NewRequest(method, url, payload)
if err != nil {
fmt.Println(err)
return
}
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
client := &http.Client {}
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := io.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
Java
import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/webhooks/")
.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
"""
{
\"webhook\": {
\"name\": \"Updated Webhook Name\"
}
}""");
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()
.url(urlBuilder.build())
.method("PATCH", body)
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", basicAuth)
.build();
Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var data = JSON.stringify({
"webhook": {
"name": "Updated Webhook Name"
}
});
var config = {
method: 'PATCH',
url: 'https://support.zendesk.com/api/v2/webhooks/',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
},
data : data,
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
Python
import requests
import json
from requests.auth import HTTPBasicAuth
url = "https://support.zendesk.com/api/v2/webhooks/"
payload = json.loads("""{
"webhook": {
"name": "Updated Webhook Name"
}
}""")
headers = {
"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(
"PATCH",
url,
auth=auth,
headers=headers,
json=payload
)
print(response.text)
Ruby
require "net/http"
require "base64"
uri = URI("https://support.zendesk.com/api/v2/webhooks/")
request = Net::HTTP::Patch.new(uri, "Content-Type": "application/json")
request.body = %q({
"webhook": {
"name": "Updated Webhook Name"
}
})
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
http.request(request)
end
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"
}
}
}'
curl to patch webhook and delete all custom headers
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": {
"custom_headers": null
}
}'
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
}
}'
curl to patch webhook custom headers
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": {
"custom_headers": {
"header_one": "new_value_one",
"header_two": "new_value_two",
"header_to_delete": null
}
}
}'
curl to patch webhook API key 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": "api_key",
"data": {
"name": "{header_name}",
"value": "{header_value}"
},
"add_position": "header"
}
}
}'
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"
}
}'
curl to patch webhook basic authentication password
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": {
"data": {
"password": "{password}"
}
}
}
}'
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"
}
}
}'
Example response(s)
204 No Content
// Status 204 No Content
null
400 Bad Request
// Status 400 Bad Request
{
"errors": [
{
"code": "InvalidWebhookID",
"detail": "Webhook id is required",
"id": "6ef45d115c1cfe68-ORD",
"source": {
"pointer": "/webhook/id"
},
"title": "Invalid Webhook ID"
}
]
}
404 Not Found
// Status 404 Not Found
{
"errors": [
{
"code": "WebhookNotFound",
"detail": "Webhook 01EMRHACJ81KB01FZW30NE8SJ3 could not be found",
"id": "6ef45d115c1cfe68-ORD",
"title": "Webhook Not Found"
}
]
}
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 |
Code Samples
curl
curl https://{subdomain}.zendesk.com/api/v2/webhooks/{webhook_id} \
-H 'Content-Type: application/json' \
-v -u {email_address}:{password} -X DELETE
Go
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://support.zendesk.com/api/v2/webhooks/"
method := "DELETE"
req, err := http.NewRequest(method, url, nil)
if err != nil {
fmt.Println(err)
return
}
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
client := &http.Client {}
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := io.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
Java
import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/webhooks/")
.newBuilder();
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()
.url(urlBuilder.build())
.method("DELETE", null)
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", basicAuth)
.build();
Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {
method: 'DELETE',
url: 'https://support.zendesk.com/api/v2/webhooks/',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
},
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
Python
import requests
from requests.auth import HTTPBasicAuth
url = "https://support.zendesk.com/api/v2/webhooks/"
headers = {
"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(
"DELETE",
url,
auth=auth,
headers=headers
)
print(response.text)
Ruby
require "net/http"
require "base64"
uri = URI("https://support.zendesk.com/api/v2/webhooks/")
request = Net::HTTP::Delete.new(uri, "Content-Type": "application/json")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
http.request(request)
end
Example response(s)
204 No Content
// Status 204 No Content
null
400 Bad Request
// Status 400 Bad Request
{
"errors": [
{
"code": "InvalidWebhookID",
"detail": "Webhook id is required",
"id": "6ef45d115c1cfe68-ORD",
"source": {
"pointer": "/webhook/id"
},
"title": "Invalid Webhook ID"
}
]
}
404 Not Found
// Status 404 Not Found
{
"errors": [
{
"code": "WebhookNotFound",
"detail": "Webhook 01EMRHACJ81KB01FZW30NE8SJ3 could not be found",
"id": "6ef45d115c1cfe68-ORD",
"title": "Webhook Not Found"
}
]
}
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", "throttled", "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 |
Code Samples
curl
curl https://{subdomain}.zendesk.com/api/v2/webhooks/{webhook_id}/invocations \
-H 'Content-Type: application/json' \
-v -u {email_address}/token:{api_token}
Go
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://support.zendesk.com/api/v2/webhooks//invocations?filter[from_ts]=&filter[status]=&filter[to_ts]=&page[after]=&page[before]=&page[size]=&sort="
method := "GET"
req, err := http.NewRequest(method, url, nil)
if err != nil {
fmt.Println(err)
return
}
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
client := &http.Client {}
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := io.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
Java
import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/webhooks//invocations")
.newBuilder()
.addQueryParameter("filter[from_ts]", "")
.addQueryParameter("filter[status]", "")
.addQueryParameter("filter[to_ts]", "")
.addQueryParameter("page[after]", "")
.addQueryParameter("page[before]", "")
.addQueryParameter("page[size]", "")
.addQueryParameter("sort", "");
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()
.url(urlBuilder.build())
.method("GET", null)
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", basicAuth)
.build();
Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {
method: 'GET',
url: 'https://support.zendesk.com/api/v2/webhooks//invocations',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
},
params: {
'filter[from_ts]': '',
'filter[status]': '',
'filter[to_ts]': '',
'page[after]': '',
'page[before]': '',
'page[size]': '',
'sort': '',
},
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
Python
import requests
from requests.auth import HTTPBasicAuth
url = "https://support.zendesk.com/api/v2/webhooks//invocations?filter[from_ts]=&filter[status]=&filter[to_ts]=&page[after]=&page[before]=&page[size]=&sort="
headers = {
"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(
"GET",
url,
auth=auth,
headers=headers
)
print(response.text)
Ruby
require "net/http"
require "base64"
uri = URI("https://support.zendesk.com/api/v2/webhooks//invocations")
uri.query = URI.encode_www_form("filter[from_ts]": "", "filter[status]": "", "filter[to_ts]": "", "page[after]": "", "page[before]": "", "page[size]": "", "sort": "")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
http.request(request)
end
Example response(s)
200 OK
// 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&page[after]=ijkl",
"prev": "https://example.zendesk.com/api/v2/webhooks/01EWJEAEY7PC3F4NXXCK52FKAF/invocations?page[size]=100&page[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 |
Code Samples
curl
curl https://{subdomain}.zendesk.com/api/v2/webhooks/{webhook_id}/invocations/{invocation_id}/attempts \
-H 'Content-Type: application/json' \
-v -u {email_address}/token:{api_token}
Go
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://support.zendesk.com/api/v2/webhooks//invocations//attempts"
method := "GET"
req, err := http.NewRequest(method, url, nil)
if err != nil {
fmt.Println(err)
return
}
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
client := &http.Client {}
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := io.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
Java
import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/webhooks//invocations//attempts")
.newBuilder();
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()
.url(urlBuilder.build())
.method("GET", null)
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", basicAuth)
.build();
Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {
method: 'GET',
url: 'https://support.zendesk.com/api/v2/webhooks//invocations//attempts',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
},
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
Python
import requests
from requests.auth import HTTPBasicAuth
url = "https://support.zendesk.com/api/v2/webhooks//invocations//attempts"
headers = {
"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(
"GET",
url,
auth=auth,
headers=headers
)
print(response.text)
Ruby
require "net/http"
require "base64"
uri = URI("https://support.zendesk.com/api/v2/webhooks//invocations//attempts")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
http.request(request)
end
Example response(s)
200 OK
// 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 |
Code Samples
curl
curl https://{subdomain}.zendesk.com/api/v2/webhooks/{webhook_id}/signing_secret \
-H 'Content-Type: application/json' \
-v -u {email_address}/token:{api_token}
Go
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://support.zendesk.com/api/v2/webhooks//signing_secret"
method := "GET"
req, err := http.NewRequest(method, url, nil)
if err != nil {
fmt.Println(err)
return
}
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
client := &http.Client {}
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := io.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
Java
import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/webhooks//signing_secret")
.newBuilder();
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()
.url(urlBuilder.build())
.method("GET", null)
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", basicAuth)
.build();
Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {
method: 'GET',
url: 'https://support.zendesk.com/api/v2/webhooks//signing_secret',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
},
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
Python
import requests
from requests.auth import HTTPBasicAuth
url = "https://support.zendesk.com/api/v2/webhooks//signing_secret"
headers = {
"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(
"GET",
url,
auth=auth,
headers=headers
)
print(response.text)
Ruby
require "net/http"
require "base64"
uri = URI("https://support.zendesk.com/api/v2/webhooks//signing_secret")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
http.request(request)
end
Example response(s)
200 OK
// Status 200 OK
{
"signing_secret": {
"algorithm": "SHA256",
"secret": "dw8vJM1zyx3ZJRWUAEvUrULMS3IwjnMIO8ajtatR"
}
}
403 Forbidden
// Status 403 Forbidden
{
"errors": [
{
"code": "NotExpectedSystemUser",
"detail": "Expected system user app_market",
"id": "6ef45d115c1cfe68-ORD",
"title": "Not Expected System User"
}
]
}
404 Not Found
// Status 404 Not Found
{
"errors": [
{
"code": "SigningSecretNotFound",
"detail": "Signing Secret could not be found",
"id": "6ef45d115c1cfe68-ORD",
"title": "Signing Secret Not Found"
}
]
}
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 |
Code Samples
curl
curl https://{subdomain}.zendesk.com/api/v2/webhooks/{webhook_id}/signing_secret \
-H 'Content-Type: application/json' \
-v -u {email_address}/token:{api_token} -X POST
Go
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://support.zendesk.com/api/v2/webhooks//signing_secret"
method := "POST"
req, err := http.NewRequest(method, url, nil)
if err != nil {
fmt.Println(err)
return
}
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
client := &http.Client {}
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := io.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
Java
import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/webhooks//signing_secret")
.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
"""
""");
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()
.url(urlBuilder.build())
.method("POST", body)
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", basicAuth)
.build();
Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {
method: 'POST',
url: 'https://support.zendesk.com/api/v2/webhooks//signing_secret',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
},
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
Python
import requests
from requests.auth import HTTPBasicAuth
url = "https://support.zendesk.com/api/v2/webhooks//signing_secret"
headers = {
"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(
"POST",
url,
auth=auth,
headers=headers
)
print(response.text)
Ruby
require "net/http"
require "base64"
uri = URI("https://support.zendesk.com/api/v2/webhooks//signing_secret")
request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
http.request(request)
end
Example response(s)
201 Created
// Status 201 Created
{
"signing_secret": {
"algorithm": "SHA256",
"secret": "dw8vJM1zyx3ZJRWUAEvUrULMS3IwjnMIO8ajtatR"
}
}
403 Forbidden
// Status 403 Forbidden
{
"errors": [
{
"code": "NotExpectedSystemUser",
"detail": "Expected system user app_market",
"id": "6ef45d115c1cfe68-ORD",
"title": "Not Expected System User"
}
]
}
404 Not Found
// Status 404 Not Found
{
"errors": [
{
"code": "WebhookNotFound",
"detail": "Webhook 01EMRHACJ81KB01FZW30NE8SJ3 could not be found",
"id": "6ef45d115c1cfe68-ORD",
"title": "Webhook Not Found"
}
]
}