Zendesk messaging conversation created webhook: A complete implementation guide

Real-time notifications are the backbone of modern support workflows. When a customer starts a conversation, your systems need to know immediately, not when someone manually checks for updates. Webhooks fill this gap.

But here's the thing about Zendesk: they have two completely different webhook systems, and the "conversation created" webhook works differently than most people expect. This guide cuts through the confusion and shows you exactly how to set up and use conversation webhooks in Zendesk, whether you're building AI integrations, syncing data to your CRM, or routing notifications to Slack.

What is the Zendesk messaging conversation created webhook?

Let's clear up a common misconception first. When people search for "Zendesk messaging conversation created webhook," they're usually thinking of the Sunshine Conversations messaging platform (the infrastructure powering Zendesk Messaging). But the actual "conversation created" event lives in a different system entirely.

Zendesk has two webhook architectures:

Standard Zendesk Webhooks handle tickets, users, organizations, and yes, conversation events. These live in Admin Center under Apps and integrations.

Messaging Webhooks (Sunshine Conversations) handle real-time chat messages through the messaging platform. These are configured separately and use different event types.

The conversation.created event you're looking for? It's part of the standard webhook system, not the messaging platform. This trips up a lot of developers who expect to find it in the messaging documentation.

So what does this webhook actually do? When a new conversation starts in your Zendesk account, whether from the Web Widget, mobile SDK, WhatsApp, or any other channel, this webhook fires and sends a payload to your endpoint with all the conversation details. Your application can then react in real time: trigger an AI agent, log to your data warehouse, send a notification, or route the conversation based on the source channel.

Prerequisites for setting up messaging webhooks

Before you start configuring webhooks, make sure you have:

• Admin access to Zendesk Admin Center - You'll need permissions to create webhooks and manage integrations
• An endpoint URL ready to receive payloads - This should be a publicly accessible HTTPS URL that can accept POST requests
• Basic understanding of webhook security - You'll want to verify signatures to ensure requests are actually from Zendesk
• A plan for handling retries and failures - Your endpoint needs to respond within 12 seconds or Zendesk will retry

One important limitation to know: trial accounts are capped at 10 webhooks and 60 invocations per minute. If you're testing on a trial, plan accordingly.

How to create a conversation webhook in Zendesk

There are two ways to set up your webhook: through the Admin Center UI or via the API. The UI is faster for one-off setups, while the API works better if you're automating deployments or managing multiple environments.

Using the Admin Center

Step 1: Access the webhooks section

Navigate to Admin Center, then click Apps and integrations in the sidebar. Select Webhooks > Webhooks from the submenu.

Step 2: Create the webhook

Click Create webhook and choose your connection method. For conversation events, select Zendesk events (not Trigger or Automation).

The connection method choice is permanent. Once you create a webhook as "Zendesk events," you can't convert it to a trigger-based webhook later. If you need both event types, create separate webhooks.

Step 3: Configure webhook settings

Fill in the basic configuration:

• Name and Description - Use something descriptive like "New Conversation Notifications" so your team knows what it does
• Endpoint URL - Your HTTPS endpoint that will receive the payloads
• Request method - POST (this is fixed for event-subscribed webhooks)
• Request format - JSON (also fixed for event subscriptions)

Step 4: Select the conversation created event

In the event subscriptions section, select zen:event-type:conversation.created from the dropdown. You can subscribe to multiple events if needed (like conversation.updated or conversation.closed).

Step 5: Set up authentication

Choose your authentication method:

For production, you should also enable signature verification. Zendesk signs each request with HMAC SHA256, and you can verify the signature against your webhook's signing secret to ensure requests are legitimate.

Using the API

For programmatic setup, use the Webhooks API:

curl -X POST https://{subdomain}.zendesk.com/api/v2/webhooks \
  -u {email_address}/token:{api_token} \
  -H "Content-Type:application/json" \
  -d '{
    "webhook": {
      "name": "Conversation Created Webhook",
      "status": "active",
      "endpoint": "https://your-endpoint.com/webhook",
      "http_method": "POST",
      "request_format": "json",
      "subscriptions": [
        "zen:event-type:conversation.created"
      ],
      "authentication": {
        "type": "bearer_token",
        "data": {
          "token": "YOUR_TOKEN"
        },
        "add_position": "header"
      }
    }
  }'

The API returns a unique webhook ID that you'll use for monitoring and updates.

Understanding the conversation created webhook payload

When a conversation is created, Zendesk sends a JSON payload to your endpoint. Here's what you can expect:

{
  "account_id": 21825834,
  "detail": {
    "id": "141"
  },
  "event": {
    "conversation_id": "67ab5f53a96f98663935c3f2",
    "created_at": "2025-02-11T14:32:05Z",
    "source_channel": "web",
    "participant_count": 1
  },
  "id": "01JQMQH83YNAKWSWJ8B1QH2NSC",
  "subject": "zen:ticket:141",
  "time": "2025-02-11T14:32:05.254571515Z",
  "type": "zen:event-type:conversation.created",
  "zendesk_event_version": "2022-11-06"
}

Key fields to pay attention to:

• detail.id - The ticket ID associated with this conversation
• event.conversation_id - The unique conversation identifier
• event.source_channel - Where the conversation originated (web, whatsapp, facebook, etc.)
• type - The event type that triggered this webhook

The payload structure differs from messaging webhooks (which use a nested events array with conversation:message types). Standard conversation webhooks have a flatter structure focused on the conversation lifecycle rather than individual messages.

Authentication and security best practices

Webhooks are only as secure as your verification process. Since your endpoint is publicly accessible, you need to verify that requests actually come from Zendesk.

Signature verification

Every webhook request includes two headers:

• X-Zendesk-Webhook-Signature - The HMAC SHA256 signature
• X-Zendesk-Webhook-Signature-Timestamp - Unix timestamp of when the request was sent

To verify a request:

1. Extract both headers from the incoming request
2. Concatenate the timestamp and request body (timestamp + "." + body)
3. Generate an HMAC SHA256 hash using your webhook's signing secret
4. Base64 encode the result
5. Compare to the signature header

The algorithm is: base64(HMACSHA256(TIMESTAMP + "." + BODY))

You can find your signing secret in Admin Center by clicking "Reveal secret" on your webhook's settings page. For testing before you create the webhook, use this static test secret: dGhpc19zZWNyZXRfaXNfZm9yX3Rlc3Rpbmdfb25seQ==

HTTPS requirement

Always use HTTPS endpoints for production webhooks. Besides the security benefits, some features like custom headers and certain authentication methods only work with HTTPS.

Idempotency

Zendesk makes a best effort to deliver webhooks exactly once, but they can't guarantee it. Your endpoint might receive the same conversation created event multiple times, especially during retries or if the circuit breaker activates.

Design your handler to be idempotent: check if you've already processed a conversation ID before taking action. This prevents duplicate notifications, duplicate CRM entries, or triggering the same automation twice.

Handling webhook events in your application

Here's a basic pattern for handling conversation webhooks in Node.js:

const crypto = require('crypto');

app.post('/webhook', (req, res) => {
  // Verify signature
  const signature = req.headers['x-zendesk-webhook-signature'];
  const timestamp = req.headers['x-zendesk-webhook-signature-timestamp'];
  const payload = JSON.stringify(req.body);

  const expectedSignature = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(`${timestamp}.${payload}`)
    .digest('base64');

  if (signature !== expectedSignature) {
    return res.status(401).send('Invalid signature');
  }

  // Process the event asynchronously
  const event = req.body;

  if (event.type === 'zen:event-type:conversation.created') {
    // Queue for processing - don't block the response
    processConversationCreated(event);
  }

  // Respond quickly to prevent retries
  res.status(200).send('OK');
});

The key principles:

• Verify the signature before processing
• Respond with 200 OK quickly (within 12 seconds)
• Process the event asynchronously - don't let your business logic block the HTTP response
• Handle duplicate events gracefully

Common integration patterns

AI Agent Triggering - When a conversation is created, check if an AI agent should handle it first before routing to human agents. Check the source channel, time of day, or customer segment to make the routing decision.

CRM Logging - Log the conversation start in your CRM for reporting and analytics. Include the channel source to understand where customers are reaching out from.

Slack Notifications - Send a notification to a Slack channel when high-priority conversations start, or route different channels to different Slack channels based on the source.

If you're building AI integrations and want to skip the webhook development entirely, eesel AI connects directly to Zendesk and handles conversation processing without requiring custom webhook handlers. We listen for conversation events and automatically generate contextual responses based on your knowledge base.

Troubleshooting common webhook issues

Even properly configured webhooks can fail. Here's how to diagnose and fix the most common problems:

Connection errors

Circuit breaker activation

If your endpoint starts returning errors, Zendesk's circuit breaker will kick in to protect your server from being overwhelmed. It triggers when a significant percentage of requests fail within a short time window.

When activated, webhooks pause briefly. After the pause, Zendesk tries again. If that request fails, the circuit breaker triggers another pause. This cycle continues until a request succeeds.

Note: The circuit breaker typically won't activate on low-volume webhooks, so small testing environments are generally safe from accidental lockouts.

Debugging tips

• Check the webhook activity logs in Admin Center (retained for 7 days)
• Filter by status to see failed invocations: add ?filter[status]=failed to the API request
• Use tools like ngrok or Hookdeck to inspect actual payloads during development
• Verify your payload format matches what your endpoint expects - the structure differs between standard webhooks and messaging webhooks

Retry behavior reference

Streamline webhook integrations with eesel AI

Building custom webhook handlers takes significant development time. You need to handle signature verification, retry logic, idempotency, and error handling before you even get to your actual business logic. Then there's the ongoing maintenance: monitoring, logging, and updating as Zendesk's APIs evolve.

If your goal is AI-powered support automation rather than webhook infrastructure, there's a simpler path.

eesel AI connects directly to your Zendesk account and handles all the webhook complexity for you:

• Real-time conversation processing - We ingest ticket and messaging events as they happen, with no webhook development required on your end
• Contextual AI responses - Our system uses your knowledge base, past tickets, and help center articles to generate replies that match your brand voice
• Actions beyond text - Look up orders in Shopify, process refunds, update ticket fields, and more, all configured through natural language instructions rather than code
• Gradual rollout - Start with copilot mode where agents review AI drafts, then move to autonomous responses as you gain confidence

The setup takes minutes, not days. Connect your Zendesk account, train on your existing data, and choose your mode. You can run simulations on past tickets to verify quality before going live.

Mature deployments using eesel AI achieve up to 81% autonomous resolution with typical payback periods under 2 months. If you're considering building custom webhook handlers for AI integration, try eesel AI free for 7 days first and see if it covers your use case.

Start building with Zendesk conversation webhooks today

The conversation created webhook is a powerful tool for real-time support automation. Whether you're triggering AI agents, syncing data to external systems, or routing notifications, understanding how to properly configure and handle these webhooks is essential.

Remember the key distinction: standard webhooks handle conversation lifecycle events (created, updated, closed), while messaging webhooks handle real-time message flow. The conversation.created event lives in the standard webhook system, and it's your entry point for reacting to new customer conversations across all channels.

Start with the Admin Center UI to get familiar with the payload structure, then move to the API when you're ready to automate. Enable signature verification from day one, design for idempotency, and respond quickly to prevent retry storms.

For teams building AI-powered support without the infrastructure overhead, eesel AI eliminates the need for custom webhook handlers while delivering contextual, knowledge-based responses. Either way, real-time conversation awareness is now within reach.