Как управлять вебхуками

Вебхуки отправляют события из Klang на ваш сервер. С их помощью можно обновлять CRM, публиковать сообщения в чате или запускать любой процесс, когда встреча обработана.

Вебхуки личные. Каждый вебхук принадлежит одному пользователю и получает события только о том содержимом, к которому у этого пользователя есть доступ.

Как создать вебхук

1. Откройте Настройки → Разработчикам → Вебхуки
2. Нажмите Создать вебхук

3. Введите URL, на который будут приходить события. Это должна быть публичная конечная точка HTTPS
4. Необязательно: добавьте Описание, чтобы потом узнать вебхук
5. Выберите, на какие События подписаться. По умолчанию выбраны все три
6. Нажмите Создать

После создания Klang покажет Ключ подписи. Скопируйте его и сохраните в надежном месте. Позже его также можно посмотреть на странице вебхука. С его помощью вы будете проверять, что входящие запросы приходят от Klang.

Доступные события

• conversation.ready: расшифровка и анализ с помощью ИИ готовы, их можно получить
• conversation.failed: не удалось обработать встречу или файл
• conversation.deleted: встреча или файл удалены

Данные каждого события содержат ID события, его тип и ссылку на разговор. Полную схему данных, формат заголовка подписи и пример кода проверки смотрите в документации по вебхукам.

События и автоматизации

Конечная точка на этой странице может получать два разных вида данных, и полезно понимать, что именно вы настраиваете.

События сообщают, что что-то произошло. conversation.ready содержит ID, название и статус, а затем ваш сервер сам получает через API нужное содержимое.

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

Конечная точка, которую используют только автоматизации, не подписана ни на одно событие, поэтому на этой странице у нее не будет выбранных событий. Так и должно быть.

Как отслеживать доставки

Выберите любой вебхук, чтобы открыть его страницу.

На странице вебхука есть:

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

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

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

Чтобы проверить, работает ли конечная точка:

1. Откройте страницу вебхука
2. В правом верхнем углу нажмите Отправить тестовое событие
3. Если вебхук подписан на несколько событий, выберите, какое отправить
4. В разделе Последние доставки появится новая строка

Тестовые события отмечены тегом TEST, а их ID начинаются с evt_test_. Схема данных такая же, как у настоящего события, поэтому можно полностью проверить свой обработчик.

Как приостановить или удалить вебхук

На странице вебхука:

• Чтобы приостановить вебхук, отключите Получение событий. Klang перестанет отправлять события, но сохранит вебхук и его историю
• Чтобы удалить вебхук, нажмите Изменить, а затем Удалить вебхук внизу окна

Приостановить или удалить вебхук можно и из меню … в списке вебхуков.

Что дальше

• Прочитайте документацию по вебхукам, чтобы узнать о схемах данных и проверке подписи
• Как управлять интеграциями: отправляйте события через встроенные сервисы, например Slack