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}:{password}

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 "username:password"

	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", "");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
		.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 "username:password"
  },
  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

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",
}

response = requests.request(
	"GET",
	url,
	auth=('<username>', '<password>'),
	headers=headers
)

print(response.text)

Ruby

require "net/http"
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")
request.basic_auth "username", "password"
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 and signing_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 username:password \
--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 "username:password"

	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\"
    ]
  }
}""");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("POST", body)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
		.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 "username:password"
  },
  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

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",
}

response = requests.request(
	"POST",
	url,
	auth=('<username>', '<password>'),
	headers=headers,
	json=payload
)

print(response.text)

Ruby

require "net/http"
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"
    ]
  }
})
request.basic_auth "username", "password"
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}:{password} -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}:{password} -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}:{password} -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}:{password} -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}:{password} -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 username:password \
--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 "username:password"

	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\"
  }
}""");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("POST", body)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
		.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 "username:password"
  },
  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

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",
}

response = requests.request(
	"POST",
	url,
	auth=('<username>', '<password>'),
	headers=headers,
	json=payload
)

print(response.text)

Ruby

require "net/http"
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"
  }
})
request.basic_auth "username", "password"
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}:{password} -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}:{password} -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}:{password} -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}:{password} -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}:{password}

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 "username:password"

	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();

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
		.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 "username:password"
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests

url = "https://support.zendesk.com/api/v2/webhooks/"
headers = {
	"Content-Type": "application/json",
}

response = requests.request(
	"GET",
	url,
	auth=('<username>', '<password>'),
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://support.zendesk.com/api/v2/webhooks/")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
request.basic_auth "username", "password"
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 and signing_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 username:password \
--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 "username:password"

	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\"
    ]
  }
}""");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("PUT", body)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
		.build();
Response response =