Входящие вебхуки

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

Как это работает

{  "message": "Текст сообщения"}

Настройки

Настройки входящего вебхука находятся на вкладке Входящий вебхук в карточке бота и появляются после включения. Кнопка Удалить вебхук внизу вкладки выключает его: прежний адрес отвечает 404 на любой запрос, а настройки и шаблон удаляются. Если включить вебхук снова, у него будет новый адрес.

Вкладка «Входящий вебхук» в карточке бота

Источник

• GitLab — пуши, пайплайны, merge request и комментарии
• Grafana — алерты со скриншотами графиков
• Свой формат — любой сервис: JSON и шаблон сообщения

Для GitLab и Grafana Пачка сама разбирает запрос и собирает сообщение, поэтому шаблон нужен только своему формату.

Шаблон сообщения

По умолчанию Пачка публикует содержимое поля message из входящего JSON. Если вместо готового текста вы хотите отправлять произвольную JSON-структуру и гибко формировать сообщение из её полей — выберите формат шаблона и заполните шаблон сообщения. При пустом шаблоне в сообщение попадает поле message.

Пачка поддерживает два шаблонизатора:

• Liquid — условия, циклы, фильтры (Shopify, open source)
• Mustache — простая подстановка без логики (open source)

Шаблонизатор разбирает входящий JSON и подставляет значения полей в шаблон. Для форматирования текста (жирность, курсив, ссылки, блоки кода и пр.) используйте markdown — полный список поддерживаемых конструкций в разделе Форматирование текста.

{  "client": "Иван Петров",  "amount": 15000,  "status": "оплачен",  "project": { "name": "Pachca" }}

Заказ от {{ client }} на сумму {{ amount }} ₽ — {{ status }}Проект: {{ project.name }}

Заказ от {{ client }} на сумму {{ amount }} ₽ — {{ status }}{{#project}}Проект: {{ name }}{{/project}}

Заказ от Иван Петров на сумму 15000 ₽ — оплаченПроект: Pachca

Liquid также поддерживает:

• Условия — if, else, elsif, unless, case/when
• Циклы — for с параметрами limit, offset, reversed
• Фильтры строк — downcase, upcase, capitalize, truncate, replace, remove, strip, escape, url_encode
• Фильтры чисел — plus, minus, times, divided_by, round, ceil, floor, abs
• Фильтры массивов — join, first, last, sort, uniq, where, map, size
• Фильтры дат — date с форматированием (%d.%m.%Y, %H:%M и пр.)

Показывать превью ссылок

Если включено, Пачка разворачивает ссылки из сообщений вебхука в превью — так же, как в обычных сообщениях.

Поле для верификации

Некоторые сервисы (например, monday.com) при настройке вебхука отправляют проверочный запрос и ожидают получить в ответе определённое поле. Укажите название поля проверки — Пачка ответит JSON-объектом с этим полем и его значением. Для monday.com это слово challenge.

Через API

Все эти настройки можно задать и программно — в объекте webhook методов POSTНовый бот и PUTРедактирование бота:

• kind — источник: simple для своего формата, gitlab или grafana
• template — шаблон сообщения
• template_engine — шаблонизатор (liquid или mustache)
• challenge_key — поле для верификации
• link_preview_enabled — показывать превью ссылок

Текущие значения возвращаются в объекте бота и доступны через метод GETИнформация о боте. Если у токена есть скоуп bots:write и вы можете управлять токенами бота, этот метод отдаёт и адрес вебхука в поле webhook.url, и тело последнего запроса на него в поле webhook.last_request_body: по нему видно, что именно прислал сервис.

Бот, созданный через API, принимает запросы в своём формате сразу, с шаблонизатором Liquid по умолчанию. Пустой бот, созданный с empty: true, входящего вебхука не имеет, пока ему не задали kind, а шаблонизатор у него по умолчанию Mustache. Mustache ставится и после удаления входящего вебхука, когда его включают снова. Чтобы шаблон работал на Liquid, передайте template_engine: "liquid" вместе с kind.

Ограничения

• Формат запроса — Пачка принимает тело в форматах application/json, application/x-www-form-urlencoded и multipart/form-data. На запрос с другим заголовком Content-Type или без него вебхук отвечает 415 и перечисляет допустимые форматы в тексте ответа, сообщение не публикуется.
• Максимальная длина сообщения — 40 000 байт, а в пространстве с продвинутым шифрованием — 27 000. Для кириллицы 40 000 байт — это около 20 000 символов, поскольку каждый символ занимает два байта. Если результат шаблона превышает лимит, сообщение не будет отправлено.
• Пустое сообщение — если шаблон возвращает пустую строку, сообщение не будет отправлено.
• Ошибка в шаблоне — если шаблон содержит синтаксическую ошибку, в чат будет отправлено сообщение вида Ошибка в шаблоне: описание ошибки.