Подписки на события: Syncra сообщает вашему сервису
Как настроить, чтобы Syncra отправляла на ваш адрес запрос, когда в рабочем пространстве пришло сообщение, создана задача или изменена страница, и как проверить подпись.
Входящий вебхук — это адрес, по которому ваш сервис пишет в Syncra. Подписка на события работает наоборот: Syncra пишет вашему сервису. Когда происходит выбранное событие, Syncra отправляет на ваш адрес запрос с его описанием. Так ваш сервис узнаёт, что бота упомянули, создали задачу или поменяли страницу, и ему не нужно постоянно спрашивать Syncra, что нового.
Подписку создаёт владелец или администратор рабочего пространства. Подписка привязана к боту, поэтому сначала нужен бот. Ещё нужен адрес вашего сервиса в интернете, который принимает POST-запросы, то есть HTTP-запросы, которыми передают данные.
Как создать подписку
- Откройте настройки рабочего пространства, вкладку «Боты», страницу бота.
- В разделе «Подписки на события» введите «Адрес запроса».
- Отметьте «События». Они разбиты на три группы: «Чат», «Задачи» и «Вики».
- Нажмите «Добавить подписку».
- В строке новой подписки нажмите «Отправить тест». Рядом появится сообщение «Тест поставлен в очередь — смотрите журнал отправок.» Результат ищите в списке «Последние отправки».
У каждой подписки свой секрет подписи. По нему ваш сервис проверяет, что запрос пришёл от Syncra.
Какие бывают события
- «Бота упомянули», «Личное сообщение», «Новое сообщение»
- «Задача создана», «Задача назначена», «Статус задачи изменён», «Задача выполнена», «Комментарий к задаче»
- «Страница вики создана», «Страница вики изменена»
События чата приходят только из каналов, где бот состоит. На сообщения ботов, в том числе чужих, события не приходят. События задач и страниц приходят по всему рабочему пространству, кроме действий ботов. События о задачах и страницах закрытого проекта получает только бот, который этот проект создал. Подписаться на реакции, звонки, встречи и сделки CRM нельзя.
Что приходит на ваш адрес
Запрос POST с JSON и тремя заголовками: X-Syncra-Event с названием события, X-Syncra-Timestamp со временем отправки в секундах и X-Syncra-Signature с подписью. В теле описаны событие, рабочее пространство, бот и данные сообщения, задачи или страницы.
Как проверить подпись
Syncra вычисляет подпись вида v1=<hex> как HMAC SHA-256 от строки «время, точка, тело запроса», где ключ — секрет подписки:
const expected = "v1=" + crypto
.createHmac("sha256", secret)
.update(timestamp + "." + rawBody)
.digest("hex");
Берите тело запроса как есть, до разбора JSON. Если подпись совпала, запрос пришёл от Syncra. Через сколько секунд считать запрос устаревшим, решаете вы: Syncra такого срока не задаёт.
Что делает Syncra при сбое
Syncra считает отправку успешной, если ваш адрес ответил любым кодом 2xx. Если ваш адрес ответил другим кодом, не ответил за 5 секунд или недоступен, Syncra повторяет отправку, всего до пяти попыток с растущими паузами, начиная с секунды. После пятой неудачи Syncra помечает отправку как неудачную. Вручную повторить её нельзя. События могут прийти не в том порядке, в каком произошли, поэтому порядок определяйте по данным внутри запроса.
Что ещё почитать
Обновлено: