Webhooks

Chatty can POST a JSON payload to your server whenever a key event occurs — no polling required.

Registering a webhook

Via dashboard: go to Developer API → Webhooks, paste your endpoint URL, pick which events to subscribe to, and click Add Webhook. The signing secret is shown once — copy it immediately.

Via API:

curl -X POST \
  "https://api.chatty.personaliai.com/api/v1/webhooks" \
  -H "Authorization: Bearer chatty_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/chatty-webhook",
    "events": ["lead.created", "message.assistant"]
  }'

The response includes a generated secret — save it immediately, it's shown once and never returned again (GET /api/v1/webhooks lists your webhooks' URLs and event filters, not their secrets).

Events

Event	Trigger
`lead.created`	A new lead is captured by the bot.
`message.user`	A visitor sends a message.
`message.assistant`	The bot replies.
`session.started`	First message in a new session.
`session.ended`	Session inactive for 30 minutes.

Payload format

Every webhook POST has the same envelope:

{
  "event": "lead.created",
  "bot_id": "a1b2c3d4-...",
  "session_id": "visitor-xyz-789",
  "timestamp": "2026-07-07T12:34:56Z",
  "data": { ... }
}

`lead.created` data

{
  "id": "ld_001abc",
  "name": "Sarah Chen",
  "email": "sarah@example.com",
  "phone": "+1-555-0123",
  "extra": {}
}

`message.assistant` data

{
  "message_id": "msg-uuid-011",
  "role": "assistant",
  "content": "Yes! Our Enterprise plan includes unlimited bots, SSO, and dedicated support.",
  "latency_ms": 820
}

Signature verification

Every request includes an X-Chatty-Signature header — an HMAC-SHA256 of the raw request body signed with your webhook secret.

Python — verify signature

import hmac, hashlib
 
def verify(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Node.js — verify signature

import crypto from "crypto"
 
function verify(payload: Buffer, signature: string, secret: string): boolean {
  const expected = crypto.createHmac("sha256", secret)
    .update(payload).digest("hex")
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))
}

Always verify the signature before processing the payload. Reject requests where verification fails with a 401 response.

Retries

Chatty retries failed deliveries (non-2xx or timeout) with exponential back-off: after 1s, 5s, 30s, 5min, 30min, 2h, 8h. After 7 attempts the event is dropped.

Return a 200 as fast as possible — offload processing to a queue. Webhooks time out after 10 seconds.

Manual products and media items can be updated from an ERP, PIM, store, or spreadsheet automation. Open Dashboard → Knowledge → Products & Media → Add Custom Product (or Add Video Clip), set the item's External ID, and enable the catalog webhook. Chatty shows a separate signed delivery URL and one-time signing secret for each bot.

Product identity

The bot_id in the catalog webhook URL scopes the lookup. Within that bot, Chatty matches the exact, case-sensitive external_id from your source system. Keep this value stable and unique for every manual catalog item. Use an ERP key, SKU namespace, or provider ID such as ERP-10042 or shopify:gid://shopify/Product/123; do not use a title, URL, price, array position, or Chatty's internal UUID.

Field	Purpose
`bot_id` (URL)	Selects the bot's catalog.
`external_id`	Stable source-system key used for create, update, and delete.
`item_id` (response)	Chatty's internal UUID, returned for diagnostics only.
`sku`	Search/display data; it is not the webhook lookup key.

Send the same external_id for every lifecycle event:

{
  "event": "product.updated",
  "external_id": "ERP-10042",
  "item": {
    "price": 79.99,
    "metadata": {"in_stock": true}
  }
}

external_id is required for updates and deletes and is limited to 256 characters. If duplicate IDs exist in a bot, Chatty returns 409 rather than changing an arbitrary product. The WhatsApp and commerce guide also covers the signed payload and catalog event details.

Testing locally

Use a tunnel like ngrok or Cloudflare Tunnel to expose your local server:

ngrok http 3000
# Chatty webhook URL: https://abc123.ngrok.io/chatty-webhook

Team & Permissions

BYOK