Вебхуки: получаем события у себя

Вебхук — это уведомление вашей системе о том, что что-то произошло в DeskAI. Мы сами отправляем запрос на ваш адрес, и вам не нужно опрашивать API.

Какие события есть

• обращение создано;
• обращение изменено — статус, ответственный, категория;
• новое сообщение в обращении — и от клиента, и от оператора;
• создан контакт.

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

Как настроить

1. Укажите адрес, на который слать события. Он должен быть доступен из интернета и работать по HTTPS.
2. Отметьте события.
3. Сохраните — при создании подписки выдаётся секрет.

Секрет и проверка подлинности

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

Проверка подписи — не формальность: адрес вебхука рано или поздно становится известен, а событие «клиент написал» может запускать у вас реальные процессы.

Что приходит

Тип события и данные объекта — обращения, сообщения или контакта. Полный формат — в технической документации.

Ответ вашей стороны

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

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

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

Отдельно отключаем подписку, если адрес сообщает, что его больше нет.

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

История доставок

По каждой подписке видно, что и когда отправлялось и с каким результатом. Это первое место, куда стоит смотреть, если события «не приходят»: часто оказывается, что мы отправляли, а принимающая сторона отвечала ошибкой.

Что дальше

Публичный API: для чего он нужен. Создание и хранение API-ключа.