webhooks.manage, оно есть только у ключа на все компании.
Не путайте вебхуки с входящими хуками автоматизаций. Вебхук — это событие от Tungo к вам. Входящий хук — это событие от вашей системы к Tungo, которое запускает сценарий: см. Автоматизации.
Добавить адрес
1
Откройте «Вебхуки»
В меню кабинета нажмите Платформа, выберите раздел Вебхуки и нажмите Добавить адрес.
2
Укажите адрес сервера
Подойдёт только адрес, который начинается с
https:// и доступен из интернета. Адреса внутренней сети Tungo не принимает.3
Выберите события
Отметьте события, которые нужны этому адресу. Если не выбрать ничего, будут приходить все.
4
Скопируйте секрет подписи
После добавления экран показывает секрет вида
whsec_…. Сохраните его на своём сервере как пароль.id адреса и secret. По ключу секрет больше нигде не прочитать, его можно только сменить. В кабинете секрет можно посмотреть позже: меню адреса, пункт Показать секрет.
Какие события бывают
Имена событий передаются в полеevent_types и приходят в поле type.
- Документы для 1С:
proposal.awaiting_approval,proposal.written,proposal.failed,proposal.rejected. - Ответы ИИ-бухгалтера по ключу:
chat.turn.completed. - Разбор выписок и ЭСФ:
bank_statement.received,esf.incoming.received,batch.completed,batch.failed. - Автоматизации:
automation.run.completed,automation.run.failed,automation.run.notice,automation.write_unknown. - Баланс платформы:
platform.balance_low,platform.balance_exhausted,platform.cap_threshold_reached. - Ключи:
api_key.expiring,api_key.cap_reached. - Оплата и связь с 1С:
payment.succeeded,payment.failed,onec.connection.changed.
data лежат только id, суммы в тиынах, статусы и время. Имён, реквизитов и текста документов там нет. За подробностями обращайтесь к API по id из события. Поля data каждого события описаны в справочнике API и на вкладке «Виды событий» в разделе «Вебхуки».
Адресу можно задать ещё и channels — список id сценариев. Тогда на него приходят только события этих сценариев, например итог одного сценария в свою систему. Это поле доступно только через API.
Отправить пробное событие
В меню адреса выберите Проверочная отправка. На адрес уйдёт событие с типомping и пустым data. Оно подписано так же, как настоящие, поэтому на нём удобно проверить и приём, и подпись. Итог смотрите в пункте Попытки доставки: там видно, что ответил ваш сервер.
По API пробное событие отправляет POST /v1/workspaces/{ws}/webhooks/endpoints/{id}/test.
Проверить подпись
Каждый запрос приходит с тремя заголовками:webhook-id, webhook-timestamp и webhook-signature. Проверяйте подпись до того, как что-либо делать с событием. Иначе любой, кто узнал адрес, сможет прислать вам поддельное.
Подписывается строка из трёх частей через точку: webhook-id, webhook-timestamp и тело запроса. Тело берётся ровно в том виде, в каком пришло, до разбора JSON. Ключ подписи — это часть секрета после whsec_, раскодированная из base64. Подпись считается как HMAC-SHA256 и кодируется в base64.
standardwebhooks из npm.
Секрет меняется пунктом Перевыпустить секрет в меню адреса или запросом POST …/endpoints/{id}/secret/rotate. Ещё сутки после смены Tungo ставит в заголовок две подписи, новым и прежним секретом. Приёмник, который проверяет «совпала хотя бы одна», как в примере выше, переживёт смену без потери событий.
Повторы и дубли
Доставка считается удачной, если ваш сервер ответил любым кодом 2xx за 30 секунд. Поэтому отвечайте сразу, а долгую обработку делайте после ответа. Если ответа нет или он другой, Tungo повторяет отправку: через 5 секунд, 5 минут, 30 минут, 2 часа, 5 часов, потом шесть раз через 10 часов и ещё раз через 5 часов. Всего получается 13 попыток примерно за трое суток. После этого событие можно отправить вручную: вкладка «События», пункт Отправить ещё раз. Из-за повторов одно событие может прийти дважды. У повтора тот жеid в теле, по нему и отбрасывайте дубли. Порядок тоже не гарантируется: события могут прийти не в той последовательности, в какой случились. Сверяйте created_at, а актуальное состояние читайте через API.
Если адрес не отвечает
Адрес, который пять суток подряд не принял ни одного события, Tungo выключает сам. В списке у него состояние «Выключен», новые события на него не отправляются. Почините приёмник и включите адрес: меню адреса, пункт Включить, или запросPATCH с "enabled": true.
Не рассчитывайте, что события, которые случились, пока адрес был выключен, придут сами. Восстановите пропущенное через API: прочитайте очередь документов, запуски автоматизаций или расход за этот период.
Что дальше
- Ошибки и ограничения: что отвечает API, когда запрос не проходит.
- Автоматизации: сценарии, о запусках которых сообщают события
automation.*. - Баланс платформы и расход: события о низком балансе и как на них реагировать.