In the Zendesk Admin Center or via the Webhooks API, create a webhook targeting your HTTPS endpoint with the appropriate signing secret for payload verification.
Subscribe the webhook to AI agent conversation events such as conversation:start, message:received, and conversation:end via the Zendesk webhooks subscription API.
In your endpoint handler, validate the incoming request by computing an HMAC-SHA256 digest of the raw request body using the signing secret and comparing it to the value in the X-Zendesk-Webhook-Signature header.
Parse the event payload to extract the session ID, conversation history, and any collected variable values from the bot session.
Respond to the webhook with a 200 status within the Zendesk-specified timeout; offload any heavy processing to an async queue to avoid response timeouts that would cause Zendesk to retry delivery.
Handle duplicate event delivery by implementing idempotency checks on the event ID field in the payload; webhook retries can deliver the same event more than once.
Known gotchas
Failing to respond within the webhook delivery timeout causes Zendesk to treat the delivery as failed and retry; repeated failures may cause the webhook to be auto-disabled — monitor webhook delivery status in the Admin Center.
The signing secret for AI agent webhooks must be stored securely on the receiving server; rotating the secret requires updating both the Zendesk webhook configuration and the server-side verification logic simultaneously to avoid a verification gap.
Webhook payloads for AI agent events differ in schema from standard Zendesk Support webhooks; do not assume the shape of ticket event payloads applies to AI agent session event payloads.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp