Receiving events

Delivery

Key Chat sends JSON POST requests to your HTTPS endpoint. Delivery is at least once: return 2xx only after durable acceptance and deduplicate using id or X-KeyChat-Event-Id.

Event envelope

{
  "api_version": "1",
  "id": "<event_uuid>",
  "type": "message.created",
  "occurred_at": "2026-10-11T12:00:00Z",
  "bot_id": "<bot_uuid>",
  "data": {}
}

Retries

Delivery times out after 5 seconds. Failures retry with exponential backoff for up to 12 attempts and then become dead. Ordering between events is not guaranteed.

Webhook test

Send a test event from the bot editor and inspect delivery status, HTTP code, and the latest error without exposing the secret.

SDK practice

Read the body as bytes or an unchanged string before JSON parsing; re-serialization changes the signed payload.

To respond quickly, durably record event.id in a queue or database before returning 2xx. Redelivery of the same id must not repeat the business operation.

import { dispatchWebhook } from '@keychat/bots';

const result = await dispatchWebhook(rawBody, request.headers, process.env.KEYCHAT_WEBHOOK_SECRET!, {
  'message.created': async event => ({ ok: true }),
  '*': async () => ({})
});