Inbound Webhooks

A ZIS inbound webhook ingests an HTTP request containing event data. A job spec in a ZIS integration can use the event to trigger a ZIS flow.

A webhook is scoped to a ZIS integration and its related account.

Run in Postman

If you use Postman, you can import the ZIS Inbound Webhooks API endpoints as a collection into your Postman app, then try out different requests to learn how the API works. Click the following button to get started:

If you don't use Postman, you can sign up for a free account on the Postman website and download the app. For more information about using Postman with Zendesk APIs, see Exploring Zendesk APIs with Postman.

JSON format

Inbound Webhooks are represented as JSON objects with the following properties:

Name	Type	Read-only	Mandatory	Description
event_type	string	false	true	A descriptor of the event type that will trigger the webhook, this will be used by a ZIS job spec to identify incoming events, in conjuction with the source_system
id	string	true	true	The unique identifier of the webhook
integration	string	true	true	The name of the integration that the webhook belongs to
password	string	true	true	Credential used along with username to make a request to the created webhook path URL
path	string	true	true	The URL for the webhook created, used for receiving HTTP requests. Includes a token that uniquely identifies this webhook.
source_system	string	false	true	A descriptor of the system that will trigger the webhook. This can be used by a ZIS job spec to identify incoming events, in conjunction with the event_type
username	string	true	true	Credential used along with password to make a request to the created webhook path URL
uuid	string	true	true	The unique identifier of the webhook
zendesk_account_id	integer	true	true	The Zendesk account id

Ingest Incoming Webhook Requests

• POST /api/services/zis/inbound_webhooks/generic/ingest/{token}

This endpoint is returned in the path property of a Create Inbound Webhook response. Ingests an incoming webhook request as an event. The ingested event can trigger a ZIS flow. The maximum recommended request payload size is 200KB.

To authorize requests, use basic authentication with the username and password from the Create Inbound Webhook endpoint's response.

Parameters

Name	Type	In	Required	Description
token	string	Path	true	The unique token to identify the webhook

Example body

{
  "body": "The smoke is very colorful.",
  "subject": "My printer is on fire!"
}

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/services/zis/inbound_webhooks/generic/ingest/{token} \
-u {username}:{password} \
-X POST \
-H "Content-Type: application/json" \
-d '{"subject": "My printer is on fire!", "body": "The smoke is very colorful."}'

Go

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	url := "https://support.zendesk.com/api/services/zis/inbound_webhooks/generic/ingest/OPwn17vlTjI_c8_IfmRBAcAyx_X4Hx2r5Iy95Pje64-s"
	method := "POST"
	payload := strings.NewReader(`{
  "body": "The smoke is very colorful.",
  "subject": "My printer is on fire!"
}`)
	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/services/zis/inbound_webhooks/generic/ingest/OPwn17vlTjI_c8_IfmRBAcAyx_X4Hx2r5Iy95Pje64-s")
		.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
{
  \"body\": \"The smoke is very colorful.\",
  \"subject\": \"My printer is on fire!\"
}""");
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({
  "body": "The smoke is very colorful.",
  "subject": "My printer is on fire!"
});

var config = {
  method: 'POST',
  url: 'https://support.zendesk.com/api/services/zis/inbound_webhooks/generic/ingest/OPwn17vlTjI_c8_IfmRBAcAyx_X4Hx2r5Iy95Pje64-s',
  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/services/zis/inbound_webhooks/generic/ingest/OPwn17vlTjI_c8_IfmRBAcAyx_X4Hx2r5Iy95Pje64-s"

payload = json.loads("""{
  "body": "The smoke is very colorful.",
  "subject": "My printer is on fire!"
}""")
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/services/zis/inbound_webhooks/generic/ingest/OPwn17vlTjI_c8_IfmRBAcAyx_X4Hx2r5Iy95Pje64-s")
request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")
request.body = %q({
  "body": "The smoke is very colorful.",
  "subject": "My printer is on fire!"
})
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

null

401 Unauthorized

// Status 401 Unauthorized

"Authentication failed"

Create Inbound Webhook

• POST /api/services/zis/inbound_webhooks/generic/{integration}

Creates an inbound webhook that is used to receive HTTP requests.

Parameters

Name	Type	In	Required	Description
integration	string	Path	true	The name of the integration that the webhook belongs to

Example body

{
  "event_type": "ticket.NewReply",
  "source_system": "slack"
}

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/services/zis/inbound_webhooks/generic/{integration} \
-H "Authorization: Bearer {access_token}" \
-X POST \
-H "Content-Type: application/json" \
-d '{"source_system": "slack", "event_type": "ticket.NewReply"}'

Go

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	url := "https://support.zendesk.com/api/services/zis/inbound_webhooks/generic/my_integration"
	method := "POST"
	payload := strings.NewReader(`{
  "event_type": "ticket.NewReply",
  "source_system": "slack"
}`)
	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/services/zis/inbound_webhooks/generic/my_integration")
		.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
{
  \"event_type\": \"ticket.NewReply\",
  \"source_system\": \"slack\"
}""");
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({
  "event_type": "ticket.NewReply",
  "source_system": "slack"
});

var config = {
  method: 'POST',
  url: 'https://support.zendesk.com/api/services/zis/inbound_webhooks/generic/my_integration',
  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/services/zis/inbound_webhooks/generic/my_integration"

payload = json.loads("""{
  "event_type": "ticket.NewReply",
  "source_system": "slack"
}""")
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/services/zis/inbound_webhooks/generic/my_integration")
request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")
request.body = %q({
  "event_type": "ticket.NewReply",
  "source_system": "slack"
})
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

{
  "event_type": "ticket.NewReply",
  "id": "01FDXQXBGQRZ3XN28WKX559PR2",
  "integration": "integrationName",
  "password": "$2a$10$vP2yN5pXK.8hbIwJGcXYAefQ3SXOT/xxjERPX4bhMjMsKIUG3LjVi",
  "path": "/api/services/zis/inbound_webhooks/generic/ingest/OPwn17vlTjI_c8_IfmRBAcAyx_X4Hx2r5Iy95Pje64-s",
  "source_system": "slack",
  "username": "SkkCyESWf8ASuzKW",
  "uuid": "d339ba7f-4a42-40fc-ae75-0e93315d3d0f",
  "zendesk_account_id": 1
}

401 Unauthorized

// Status 401 Unauthorized

"Authentication failed"

Show Inbound Webhook By UUID

• GET /api/services/zis/inbound_webhooks/generic/{integration}/{uuid}

Returns webhook details by UUID

Parameters

Name	Type	In	Required	Description
integration	string	Path	true	The name of the integration that the webhook belongs to
uuid	string	Path	true	The webhook's identifier

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/services/zis/inbound_webhooks/generic/{integration}/{uuid} \
-H "Authorization: Bearer {access_token}"

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://support.zendesk.com/api/services/zis/inbound_webhooks/generic/my_integration/d339ba7f-4a42-40fc-ae75-0e93315d3d0f"
	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/services/zis/inbound_webhooks/generic/my_integration/d339ba7f-4a42-40fc-ae75-0e93315d3d0f")
		.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/services/zis/inbound_webhooks/generic/my_integration/d339ba7f-4a42-40fc-ae75-0e93315d3d0f',
  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/services/zis/inbound_webhooks/generic/my_integration/d339ba7f-4a42-40fc-ae75-0e93315d3d0f"
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/services/zis/inbound_webhooks/generic/my_integration/d339ba7f-4a42-40fc-ae75-0e93315d3d0f")
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

{
  "event_type": "ticket.NewReply",
  "id": "01FDXQXBGQRZ3XN28WKX559PR2",
  "integration": "integrationName",
  "password": "$2a$10$vP2yN5pXK.8hbIwJGcXYAefQ3SXOT/xxjERPX4bhMjMsKIUG3LjVi",
  "path": "/api/services/zis/inbound_webhooks/generic/ingest/OPwn17vlTjI_c8_IfmRBAcAyx_X4Hx2r5Iy95Pje64-s",
  "source_system": "slack",
  "username": "SkkCyESWf8ASuzKW",
  "uuid": "d339ba7f-4a42-40fc-ae75-0e93315d3d0f",
  "zendesk_account_id": 1
}

404 Not Found

// Status 404 Not Found

{
  "errors": [
    {
      "code": "1110",
      "detail": "Not Found",
      "status": "404"
    }
  ]
}