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

These nine names are the complete list. Any other name returns 400 INVALID_PARAMS. A subscription can listen to one or more events.

customer.created is the one event that belongs to no conversation, so its conversationId is null.

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

Every event carries an eventId you can de-duplicate on, and data is the only part that changes between event types.

conversationId can be passed straight to GET /chat/conversations/{id} to pull the full record. It is null on customer.created, which has no conversation, and it is not guaranteed to be the same id form on every event, so key your own storage on the firestoreId and pgConvoId that read returns, not on the raw string in the envelope.

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 7 attempts over about 9 hours. A timeout, a network error, or a 5xx schedules another try at roughly 10 seconds, 1 minute, 5 minutes, 30 minutes, 2 hours, and 6 hours. See Errors and rate limits.
• 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.
• The subscription is disabled after the seventh failure. Delivery stops for every event, not only the one that failed, until you PUT the subscription with {"isActive": true}. Turning it back on needs the Pro or Plus plan, while pausing it does not. Return 2xx quickly and do the heavy work in the background.
• 410 Gone disables the subscription immediately, with no retries. Return it only when the endpoint is permanently retired.
• A redirect is never followed. A 3xx is treated the same as a 4xx: the delivery is dropped and never retried, because a redirect target is not re-checked for safety. Register the final URL.
• A payload above 80,000 bytes arrives without its data. The envelope still comes through, and data is replaced with {"truncated": true, "originalSize": <bytes>}. Read the record back over the Chat Conversations API when you see that flag.
• Independent delivery. Each subscription is delivered separately. One failing endpoint doesn't affect the others.
• Order is not guaranteed. Every event is queued and retried on its own, so a retried event can land after one that happened later. Two messages a second apart can reach you in either order. Sort by occurredAt on the envelope, and treat an event as out of date when you already hold something newer for that conversation.
• Delivery is a notification, not a ledger. Chatty never fails a chat action because a webhook could not be queued, so a rare event may never reach you at all. If your copy has to be complete, reconcile on a schedule with the Chat Conversations API rather than rebuilding from the event stream alone.

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.