Отправлять события Slen в ваш сервис

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

4 мин чтения

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

Где находятся вебхуки

Откройте Настройки, затем Вебхуки. Строка показывает адрес, состояние вебхука — Активен или Выключен, — какие проекты он слышит, последние четыре символа его секрета и на сколько событий он подписан.

Страница открывается тому, у кого есть разрешение management:read. Для добавления и изменения вебхука нужно management:write. Вебхук всех проектов добавляет и меняет только участник, которому доступен каждый проект.

Добавить вебхук

1. Начните новый вебхук

Нажмите Новый вебхук.

2. Выберите проекты

В поле Проект выберите Все проекты или один проект. Вебхук одного проекта слышит события этого проекта.

3. Укажите адрес

Заполните URL: адрес https на порту 443, с именем хоста и без логина и пароля. Адрес, на который сервис не может доставить события, — например, ведущий в частную сеть, — отклоняется с кодом webhook_url_not_allowed.

4. Выберите события

В разделе События отметьте события, которые нужно отправлять. Нужно хотя бы одно.

5. Создайте вебхук

Нажмите Создать вебхук.

6. Сохраните секрет

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

События формы

Форма группирует события по тому, о чём они.

Группа	О чём сообщают её события
Резервирование	Холд взят, списан, освобождён или истёк, а также вызов стоил больше своего холда
Бюджеты	`budget.threshold_reached` — холд довёл использование бюджета до 50 % или 80 % его лимита; `budget.exceeded` — до всего лимита
Операции	Вызов авторизован или отклонён, начинается и заканчивается: `operation.completed`, `operation.failed` или `operation.uncertain`
Согласования	`approval.requested` — выполнение ждёт решения; `approval.decided` — его одобрили, отклонили или срок истёк

operation.failed значит, что вызова не было и его холд вернулся. Есть одно исключение: вызов, который провайдер выполнял в фоне и чей холд закрыло другое списание, пока он ждал, заканчивается operation.failed с причиной background_hold_expired, и ничего не возвращается.
operation.uncertain значит, что никто не знает, чем закончился вызов: ответ узла модели потерялся, на старт фонового вызова не ответили, или фоновый вызов перестали опрашивать. Его холд стоит, пока не истечёт, и провайдеру, возможно, заплатили. Не повторяйте такой вызов так, будто он не удался.
Вызов, который флоу передаёт провайдеру на выполнение в фоне, тоже сообщает о своём конце одним из трёх событий выше. Один такой вызов не сообщает ничего: вызов, который провайдер всё ещё называет выполняющимся, когда его выполнение прождало 72 часа (по умолчанию). Тогда выполнение закрывается как failed с parked_expired, а операция вызова остаётся pending.

Slen отправляет больше событий, чем предлагает форма, — о флоу, подключениях, выполнениях, оповещениях. Вебхук слышит их, только когда они названы среди его событий через API.

Как приходят доставки

Доставка — это POST с событием в теле, подписанный секретом вебхука.
Неудавшаяся доставка отправляется снова позже, с растущими паузами.
Одно и то же событие может прийти больше одного раза. Различайте события по их идентификатору.

Выключить или удалить вебхук

В меню в строке вебхука — Выключить (у выключенного вебхука — Включить) и Удалить. Выключенный вебхук сохраняет адрес, события и секрет, и новые события ему не отправляются. Удалить удаляет его после подтверждения, и его адрес перестаёт получать события.

Вебхуки и уведомления

Вебхук — для вашего сервиса: подписанный запрос с событием в JSON о каждом событии, на которое он подписан, который отправляется снова, пока ваш сервис его не примет. Уведомление — для людей: сообщение в почте, Telegram, Slack, Microsoft Teams или Discord об оповещении или согласовании, на языке читателя, со сводками и тихими часами. Чтобы сообщать людям, настройте Уведомления. Они не зависят от вебхуков, и событие доходит и туда, и туда.

Что читать дальше

Оповещения — оповещения, чьи alert.opened и alert.resolved может нести вебхук.
Бюджеты — когда бюджет отправляет свои события.
Журнал аудита — кто добавил, изменил или удалил вебхук.
Вебхуки — что несёт доставка, как проверить её подпись, и все события.
Уведомления — сообщать людям об оповещениях и согласованиях.