Webhooks

Webhooks позволяют зеркалировать события AskAIs Customer Service в ваши собственные системы — CRM, аналитику, Slack и всё, что работает по HTTP.

Создание webhook

Перейдите в Настройки → Webhooks → Новый webhook. Выберите события, вставьте свой URL, сохраните. Вы получите секрет, используемый для подписи полезных нагрузок.

Типы событий

• conversation.created
• conversation.updated — статус, приоритет, назначение
• conversation.resolved
• message.created — любое сообщение, любой отправитель
• contact.created
• contact.updated

Формат полезной нагрузки

POST https://your-app.com/webhooks/singlink
Content-Type: application/json
X-SingLink-Event: message.created
X-SingLink-Signature: sha256=ab12cd34...
X-SingLink-Timestamp: 1747300800

{
  "id": "evt_01HX...",
  "type": "message.created",
  "tenantId": "tnt_01HX...",
  "data": { /* event-specific payload */ }
}

Проверка подписей

Вычислите HMAC-SHA256 для timestamp + "." + rawBody с секретом webhook. Сравните его с заголовком X-SingLink-Signature (безопасно по времени).

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(req, secret) {
  const ts = req.headers["x-singlink-timestamp"];
  const sig = req.headers["x-singlink-signature"];
  const expected = "sha256=" + createHmac("sha256", secret)
    .update(ts + "." + req.rawBody)
    .digest("hex");
  return timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

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

Мы повторяем не-2xx ответы с экспоненциальной задержкой: 1s, 10s, 1m, 10m, 1h. После 5 попыток событие помечается как неудачное; вы можете увидеть сбои в администрировании.

Тестовый ping

У каждого webhook есть кнопка Отправить тест, которая отправляет фиктивное событие webhook.ping. Полезно для проверки того, что ваша конечная точка принимает подписи, перед запуском в продакшен.