Вебхуки позволяют получать уведомления в реальном времени, когда происходят события в вашем виджете чата. Когда посетитель начинает чат, отправляет форму или сообщение, Chatim отправляет HTTP POST запрос на ваш URL с данными события.
С вебхуками вы можете:
После создания вы увидите Секрет вебхука — скопируйте и сохраните его немедленно. Этот секрет используется для проверки того, что входящие запросы поступают от Chatim. Он показывается только один раз.
| Событие | Срабатывает когда |
|---|---|
chat.started | Посетитель открывает виджет чата и начинает новую сессию |
chat.message.received | Посетитель отправляет текстовое сообщение |
chat.form.submitted | Посетитель отправляет форму в потоке чат-бота |
chat.closed | Сессия чата закрывается |
chat.assigned | Агент поддержки присоединяется к разговору |
chat.handoff | Чат-бот переходит из режима бота в живой чат |
Каждая доставка вебхука — это HTTP POST запрос с JSON телом.
{
"event": "chat.started",
"eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"timestamp": "2025-01-15T10:30:00.000Z",
"projectUuid": "your-project-uuid",
"chatUuid": "visitor-chat-uuid",
"data": { }
}Включает информацию о посетителе, URL страницы, местоположение и агент пользователя.
{
"event": "chat.started",
"data": {
"visitor": {
"uuid": "visitor-uuid",
"name": "John Doe",
"email": "[email protected]",
"phone": "+1234567890"
},
"page": {
"url": "https://example.com/pricing",
"title": "Pricing - Example"
},
"location": { "country": "US", "city": "Los Angeles" },
"userAgent": { "browser": "Chrome", "os": "Windows", "device": "Desktop" }
}
}{
"event": "chat.message.received",
"data": {
"messageUuid": "message-uuid",
"message": "Hi, I have a question about your pricing.",
"visitor": { "uuid": "visitor-uuid", "name": "John Doe" }
}
}{
"event": "chat.form.submitted",
"data": {
"formNodeId": "node-id",
"formName": "Contact Form",
"fields": {
"name": "John Doe",
"email": "[email protected]",
"phone": "+1234567890",
"message": "I'd like a product demo."
},
"visitor": { "uuid": "visitor-uuid", "name": "John Doe" }
}
}Включает кто закрыл чат (agent, visitor, system или timeout), длительность в секундах, количество сообщений и транскрипт.
{
"event": "chat.closed",
"data": {
"closedBy": "agent",
"status": "closed",
"duration": 345,
"messageCount": 12,
"visitor": { "uuid": "visitor-uuid", "name": "John Doe" }
}
}Отправляется, когда агент поддержки присоединяется к разговору.
{
"event": "chat.assigned",
"data": {
"assignedTo": { "uuid": "agent-uuid", "name": "Jane Smith" },
"visitor": { "uuid": "visitor-uuid", "name": "John Doe" }
}
}Отправляется, когда чат-бот переходит в режим живого чата.
{
"event": "chat.handoff",
"data": {
"reason": "Visitor requested human support",
"fromNode": "node-id",
"visitor": { "uuid": "visitor-uuid", "name": "John Doe" }
}
}Каждый запрос вебхука содержит подпись, чтобы вы могли проверить, что он пришёл от Chatim. Подпись вычисляется как HMAC-SHA256(secret, timestamp + "." + payload) и отправляется в заголовке X-Chatim-Signature.
| Заголовок | Описание |
|---|---|
X-Chatim-Signature | HMAC-SHA256 подпись полезной нагрузки |
X-Chatim-Timestamp | Метка времени Unix, когда был отправлен запрос |
X-Chatim-Event | Тип события |
X-Chatim-Delivery-Id | Уникальный идентификатор доставки |
const crypto = require('crypto');
function verifyWebhook(req, secret) {
const signature = req.headers['x-chatim-signature'];
const timestamp = req.headers['x-chatim-timestamp'];
const body = JSON.stringify(req.body);
// Reject requests older than 5 minutes
const age = Math.floor(Date.now() / 1000) - parseInt(timestamp);
if (age > 300) return false;
const expected = 'sha256=' + crypto
.createHmac('sha256', secret)
.update(timestamp + '.' + body)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}import hmac, hashlib, time
def verify_webhook(headers, body, secret):
signature = headers.get('X-Chatim-Signature', '')
timestamp = headers.get('X-Chatim-Timestamp', '')
if abs(time.time() - int(timestamp)) > 300:
return False
expected = 'sha256=' + hmac.new(
secret.encode(),
f'{timestamp}.{body}'.encode(),
hashlib.sha256
).hexdigest()
return hmac.compare_digest(signature, expected)Если ваш эндпоинт недоступен или возвращает ошибку, Chatim автоматически повторяет попытку.
| Попытка | Задержка |
|---|---|
| 1-я повторная попытка | 1 минута |
| 2-я повторная попытка | 5 минут |
| 3-я повторная попытка | 30 минут |
| 4-я повторная попытка | 2 часа |
| 5-я повторная попытка | 24 часа |
После 5 неудачных попыток доставка помечается как неудачная. Ответы 2xx считаются успехом, 4xx — постоянными ошибками (без повтора), 5xx и тайм-ауты (30с) запускают повторные попытки.
Если вебхук накапливает 10 последовательных неудач, он автоматически отключается. Вы можете повторно включить его из панели управления после исправления проблемы.
Нажмите Тест на любом вебхуке, чтобы отправить пример события chat.started на ваш URL. Это позволяет проверить ваш эндпоинт перед запуском.
Нажмите на вебхук, чтобы просмотреть недавние доставки с типом события, меткой времени, кодом состояния HTTP и сообщениями об ошибках. История хранится 30 дней.
Если секрет вебхука скомпрометирован, нажмите Перегенерировать секрет, сохраните новый секрет и обновите ваш эндпоинт. Старый секрет немедленно становится недействительным.
Подпишитесь на chat.form.submitted и chat.started, чтобы автоматически создавать контакты и лидов в вашей CRM.
Подпишитесь на chat.assigned и chat.handoff, чтобы оповещать вашу команду, когда посетитель нуждается в живой поддержке.
Подпишитесь на все события, чтобы построить полную картину вовлечённости в чате, показателей конверсии форм и времени ответа поддержки.
Подпишитесь на chat.form.submitted, чтобы запускать приветственные письма, последовательности последующих действий или сообщения подтверждения.
eventId для обработки дублирующих доставокtimestamp + "." + raw_body (не распарсенный JSON)Начать