Получение событий

Доставка

Key Chat отправляет JSON POST на настроенный HTTPS endpoint. Доставка выполняется минимум один раз: отвечайте 2xx только после надёжной фиксации события и дедуплицируйте по id или X-KeyChat-Event-Id.

Конверт события

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

Повторные попытки

Таймаут доставки — 5 секунд. Неуспешные события повторяются с экспоненциальной задержкой до 12 попыток, после чего получают состояние dead. Порядок разных событий не гарантируется.

Тест webhook

Из редактора бота можно отправить тестовое событие. Используйте журнал доставок, чтобы увидеть код ответа и последнюю ошибку без раскрытия тела секрета.

Практика с SDK

Считывайте тело запроса как байты или неизменённую строку до JSON parsing: повторная сериализация меняет подпись.

Для быстрого ответа webhook сначала зафиксируйте event.id в очереди или БД, затем верните 2xx. Повторная доставка того же id не должна повторять бизнес-операцию.

Примеры использования

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

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