Webhooks

Overview

Webhooks let Chatty notify your server the moment something happens in a conversation. Instead of polling, you register a URL once and Chatty POSTs a JSON payload to it whenever a matching event fires.

Common uses:

• Mirror conversations into your own helpdesk or database
• Alert your team when a customer asks something the AI couldn't answer
• Log AI replies for quality review or analytics

Manage subscriptions

Subscriptions are managed with the same X-Api-Key that authenticates the rest of the Chat Conversations API.

Create a subscription

curl -s -X POST "https://app.chatty.net/chat/webhooks" \
  -H "X-Api-Key: $CHATTY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "url": "https://your-server.com/chatty-webhook",
        "events": ["message.created", "conversation.state_changed"],
        "secret": "a-long-random-signing-secret",
        "metadata": {}
      }'

Returns 201 with the created subscription. Registering a url you already use updates that subscription instead of creating a duplicate. To pause delivery without deleting, PUT the subscription with {"isActive": false}.

A bad url, a missing secret, or an unknown event name returns 400 INVALID_PARAMS with the reason in error.message.

PUT and DELETE also answer 400 INVALID_PARAMS with Subscription not found when the id is unknown or belongs to another store. They do not return 404.

Events

A subscription can listen to one or more events.

senderType is one of customer, agent, bot, or system. An AI reply is bot, a human on your team is agent.

Payload envelope

Every event uses the same envelope. Only data changes.

{
  "eventId": "b3f1c9a0-4c2e-4f1a-9b77-2d5e8a0c1f34",
  "type": "message.created",
  "shopId": "your_shop_id",
  "conversationId": "conversation_id",
  "occurredAt": "2026-08-03T12:00:00.000Z",
  "data": {
    "messageId": "msg_123",
    "text": "What is your return policy?",
    "senderType": "customer",
    "memberId": null,
    "createdAt": "2026-08-03T12:00:00.000Z"
  }
}

Legacy events

Two older event names still work. They keep their original payload shape, which does not match the envelope above, and the two shapes differ from each other.

customer_message fires when a customer sends a new message.

{
  "timestamp": "2026-06-11T10:13:52.305Z",
  "shopId": "your-shop-id",
  "shopifyDomain": "your-store.myshopify.com",
  "convoId": "conversation-id",
  "message": {
    "text": "Hi, do you have the Daris Tee in size M?",
    "createdAt": "2026-06-11T10:13:52.305Z",
    "customerEmail": "shopper@example.com",
    "customerShopifyId": "gid://shopify/Customer/123"
  },
  "context": {
    "detectedLanguage": "en",
    "country": "US",
    "locale": "en"
  }
}

ai_response fires when the AI assistant responds to a visitor. It adds query and a richer message, and carries no context.

{
  "timestamp": "2026-06-11T10:13:54.120Z",
  "shopId": "your-shop-id",
  "shopifyDomain": "your-store.myshopify.com",
  "convoId": "conversation-id",
  "query": "do you have the Daris Tee in size M?",
  "message": {
    "text": "Yes! The Daris Tee is in stock in size M.",
    "topic": "product-availability",
    "isAskBotResponse": "found",
    "chatbotProducts": [],
    "chatbotFaqs": []
  }
}

For ai_response, message.isAskBotResponse is "found" when the AI had an answer and "not-found" when it didn't. That's a useful signal for routing unanswered questions to a human. The chatbot* arrays list the sources the AI used.

Verify the signature

Every delivery carries these headers:

const crypto = require('crypto')
 
function verifyWebhook(rawBody, timestamp, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp};${rawBody}`)
    .digest('hex')
 
  const a = Buffer.from(signature)
  const b = Buffer.from(expected)
  if (a.length !== b.length) return false
  return crypto.timingSafeEqual(a, b)
}

Also check that X-Webhook-Timestamp is recent — a few minutes at most — and reject anything older. The signature alone does not expire.

Delivery behavior

• Respond within 10 seconds. Chatty aborts the request after that and counts it as a failure.
• Up to 3 attempts. Any non-2xx response or timeout is retried, with a short pause that grows between attempts.
• De-duplicate on X-Webhook-Event-Id. Every retry carries the same id. If your endpoint is slow but eventually succeeds, you can receive the same event more than once.
• No delivery after the third failure. The failure is recorded on our side, but the event is not queued for later. Return 2xx quickly and do the heavy work in the background.
• Independent delivery. Each subscription is delivered separately. One failing endpoint doesn't affect the others.

FAQs

Need help?

If your endpoint isn't receiving events, check that the url is publicly reachable over HTTPS and returns 2xx within 10 seconds. If deliveries arrive but fail verification, check that you are signing `${timestamp};${body}` and not the body alone. Still stuck? Contact the Chatty support team from your dashboard.