receptionworksСправка

Интеграции и webhooks

Передавайте диалоги, записи, вызовы сотрудника и обращения в Zapier, Make или на свой сервер, проверяйте подпись и смотрите результаты доставки.

Интеграции передают события бизнеса в другой сервис сразу, как они произошли: новый диалог, запись, вызов сотрудника, обращение. Через Zapier или Make можно, например, добавить строку в таблицу, отправить сообщение в чат или создать карточку в CRM без ручного копирования.

Где найти

Откройте «Модули» в верхнем меню, подключите модуль «Интеграции» (по умолчанию он выключен) и нажмите «Открыть интеграции» на его карточке. Откроется вкладка «Вебхуки», рядом — вкладка «Журнал событий». Раздел открывается только Владельцу и Администратору: адрес приёмника может содержать личный токен. Пока модуль выключен, события никуда не отправляются, а пропущенные не будут отправлены позже. Получатели остаются настроенными, журнал событий продолжает вестись.

Как добавить приёмник

  1. В Zapier создайте Zap с триггером «Webhooks by Zapier» и событием «Catch Hook» и скопируйте выданный адрес. В Make добавьте модуль «Custom webhook» и скопируйте его адрес.
  2. На странице интеграций заполните «Название» (например, название Zap) и «Адрес приёмника» (скопированный адрес).
  3. В «Какие события отправлять» отметьте, что отправлять.
  4. Нажмите «Добавить приёмник».
  5. Секрет подписи показывается один раз. Скопируйте его и сохраните. Zapier и Make он не нужен; ваш собственный сервер использует его для проверки подписи. Если секрет потерян, создайте новый через «Сменить секрет».
  6. На карточке приёмника нажмите «Отправить тест». Результат: Доставлено или Не доставлено с причиной.

Адрес должен быть публичным и начинаться с https. Не принимаются, и страница называет причину: адреса http, IP-адреса вместо домена, нестандартные порты, адреса с логином и паролем, внутренние адреса и адреса на доменах ReceptionWorks. Страница показывает только домен и путь адреса: часть после знака вопроса может содержать токен вашего приёмника.

Какие события отправляются

События тестового чата не отправляются. Приёмник получает только события, которые произошли после его добавления и пока он включён: то, что случилось во время паузы или отключения, позже не отправляется.

«Новое сообщение» и «Диалог целиком» несут полный текст диалогов, в том числе то, что пишут клиенты. Текст покидает ReceptionWorks и попадает к выбранному вами приёмнику, поэтому отмечайте эти события только для приёмников, которым доверяете. У нового приёмника эти два события не отмечены. Они отправляются, только пока их отметил какой-либо приёмник, и не попадают в журнал событий и его выгрузку: сам диалог есть во входящих. Тестовые чаты и заблокированные клиенты не отправляются.

Что получает приёмник

Каждое событие — это POST-запрос с телом JSON. Пример для вызова сотрудника, который запросил AI-сотрудник:

{
  "schema_version": "business-webhook.v1",
  "id": "5b0c5e2e-0000-4000-8000-000000000001",
  "type": "conversation.handoff_requested",
  "occurred_at": "2026-10-07T09:30:00.000Z",
  "business": { "name": "Example Studio" },
  "actor": { "kind": "ai_employee" },
  "channel": "telegram",
  "employee": { "name": "Anna" },
  "conversation": { "url": "https://app.example.com/businesses/studio/inbox?conversation=example" },
  "customer": { "name": "Maria", "email": "maria@example.com", "phone": "+1 555 0100" },
  "booking": null,
  "handoff": { "reason": "ai_request", "reason_text": "The customer wants to discuss a discount" },
  "support_case": null
}

Разделы, которые к событию не относятся, равны null. У тестового события из «Отправить тест» тип webhook.test, и все разделы, кроме business, равны null. В данных нет переведённых текстов: названия переданы как сохранены, коды — фиксированные английские слова, а время указано по UTC.

"message": {
  "id": "6c1d0f52-0000-4000-8000-000000000002",
  "sequence": 12,
  "author": "customer",
  "text": "Hello, can I book for Friday?",
  "created_at": "2026-10-07T09:29:41.000Z",
  "attachments": [{ "kind": "image", "name": "photo.jpg", "media_type": "image/jpeg" }]
}

Сообщения и диалоги целиком могут приходить не по порядку и повторяться, поэтому не полагайтесь на порядок прихода. По sequence восстанавливайте порядок сообщений в диалоге, а доставку с уже обработанным webhook-id отбрасывайте. Диалог целиком повторяет сообщения, которые вы могли уже получить по одному: используйте его, чтобы проверить или восстановить весь диалог.

Как проверить подпись

В каждом запросе три заголовка стандарта Standard Webhooks: webhook-id, webhook-timestamp и webhook-signature. Zapier и Make их не проверяют. На своём сервере используйте официальную библиотеку Standard Webhooks для вашего языка: передайте ей секрет в точности как показан (он начинается с whsec_), исходное неизменённое тело запроса и три заголовка. Проверка вручную:

signed_content = webhook-id + "." + webhook-timestamp + "." + raw request body
signature      = "v1," + base64( HMAC-SHA256( key, signed_content ) )
key            = base64-decoded part of the secret after "whsec_"

Заголовок webhook-signature содержит v1, и подпись. После «Сменить секрет» в нём две подписи через пробел: принимайте запрос, если совпала любая. Отклоняйте запросы, у которых время отличается от вашего больше чем на пять минут.

Повторы и автоматическое отключение

Приёмник должен ответить кодом 2xx за 10 секунд. Перенаправления не выполняются: адрес, который перенаправляет, считается ошибкой. Иначе ReceptionWorks повторяет отправку: сразу, затем через 1 минуту, 5 минут, 30 минут, 2 часа, 6 часов и 12 часов. Это 7 попыток примерно за 21 час. Если все неудачны, доставка получает статус Не доставлено в «Журнал доставок», и вы можете нажать «Отправить повторно». Повторы идут с тем же webhook-id, поэтому приёмник может отбрасывать дубли.

Приёмник отключается автоматически, если отвечает, что адреса больше нет (код 410), или если пять событий подряд не доставлены. Тогда на карточке появляется «Отключён автоматически» с причиной, а команда получает уведомление. Исправьте адрес и нажмите «Включить»: события, пропущенные за это время, не отправляются.

Пауза, новый секрет, удаление

Что важно знать

Что дальше

← Все статьи