Исходящие вебхуки
Исходящий вебхук отправляет HTTP POST-запрос в ваше приложение, когда в канале появляется подходящее сообщение, и публикует ответ приложения в Loop. Например, сообщение #build в канале builds может запускать сборку и возвращать её результат.
Исходящие вебхуки работают только в публичных каналах. Для частных каналов и личных сообщений используйте slash-команды.
Создание вебхука
- Откройте Главное меню > Интеграции > Исходящие вебхуки и нажмите Добавить исходящий Webhook.
- Заполните Заголовок (до 64 символов) и при необходимости Описание (до 500 символов).
- Выберите Тип содержимого запроса:
application/x-www-form-urlencoded— параметры кодируются в теле запроса как форма;application/json— тело запроса в формате JSON.
- Укажите Канал, Ключевые слова (по одному на строку) или и то и другое:
- только канал — вебхук срабатывает на каждое сообщение в этом публичном канале;
- только ключевые слова — на сообщения с ними во всех публичных каналах команды;
- канал и ключевые слова — сообщение должно соответствовать обоим условиям.
- Если указаны ключевые слова, выберите Условие срабатывания:
- Первое слово соответствует слову события полностью;
- Первое слово начинается со слова триггера.
- Укажите URL обратного вызова (по одному на строку) — адреса, куда Loop будет отправлять запросы. Если адрес во внутренней сети, администратор должен добавить его в список доверенных (см. Разработка на локальной машине).
- Нажмите Сохранить и скопируйте Токен — по нему приложение будет проверять, что запрос пришёл от Loop.
Исходящими вебхуками управляют пользователи с разрешением Управление исходящими вебхуками — по умолчанию системные администраторы и администраторы команд. Сами исходящие вебхуки включаются в Системная консоль > Интеграции > Управление интеграцией > Разрешить исходящие вебхуки (включено по умолчанию).
Запрос от Loop
Когда сообщение подходит под условия, Loop отправляет POST-запрос на каждый URL обратного вызова. Пример с типом application/x-www-form-urlencoded:
POST /my-endpoint HTTP/1.1
Host: builds.example.ru
Accept: application/json
Content-Type: application/x-www-form-urlencoded
token=zmigewsanbbsdf59xnmduzypjc&
team_id=kwoknj9nwpypzgzy78wkw516qe&
team_domain=someteam&
channel_id=hawos4dqtby53pd64o4a4cmeoo&
channel_name=builds&
timestamp=1445532266&
user_id=rnina9994bde8mua79zqcg5hmo&
user_name=ivan&
post_id=axdygg1957njfe5pu38saikdho&
text=%23build+main&
trigger_word=%23build&
file_ids=&
root_id=
| Поле | Описание |
|---|---|
token | Токен вебхука. Сравнивайте его с сохранённым значением и отклоняйте запросы с другим токеном |
team_id, team_domain | ID и имя команды |
channel_id, channel_name | ID и имя канала |
timestamp | Время сообщения. В форме — Unix-время в секундах, в JSON — в миллисекундах |
user_id, user_name | Автор сообщения |
post_id | ID сообщения |
text | Текст сообщения |
trigger_word | Сработавшее ключевое слово (пусто, если вебхук настроен только на канал) |
file_ids | ID прикреплённых файлов через запятую |
root_id | ID корневого сообщения, если сообщение отправлено в треде |
Ответ приложения
Чтобы опубликовать ответ в канале, верните JSON с заголовком Content-Type: application/json:
{
"text": "Сборка **main** запущена :rocket:"
}
Если ответ не нужен, верните пустое тело или JSON без text и attachments.
Параметры ответа
| Параметр | Описание | Обязательный |
|---|---|---|
text | Текст сообщения с поддержкой Markdown. Упоминания @username, @channel, @here работают как в обычных сообщениях. | Да, если нет attachments |
response_type | comment — ответить в треде исходного сообщения; post или пусто — обычное сообщение в канале. По умолчанию post. | Нет |
username | Имя отправителя. Работает, если разрешено переопределение имён. По умолчанию — имя из настроек вебхука. | Нет |
icon_url | Адрес изображения профиля. Работает, если разрешено переопределение изображений. | Нет |
attachments | Вложения для расширенного оформления. | Да, если нет text |
type | Тип сообщения, обычно для плагинов. Должен начинаться с custom_. При передаче attachments игнорируется. | Нет |
props | Произвольные данные сообщения в JSON. Ключи from_webhook, override_username, override_icon_url и webhook_display_name задаёт сам Loop. | Нет |
priority | Приоритет сообщения: объект с полем priority (important или urgent). | Нет |
Пример ответа с несколькими параметрами:
{
"response_type": "comment",
"username": "test-automation",
"icon_url": "https://example.ru/icon.png",
"text": "#### Результаты тестов за 27 июля\n\n| Компонент | Запущено | Упало |\n| --- | --- | --- |\n| Сервер | 948 | :white_check_mark: 0 |\n| Веб-клиент | 123 | :warning: 2 [(подробнее)](https://example.ru/logs) |\n| iOS | 78 | :warning: 3 [(подробнее)](https://example.ru/logs) |",
"props": {
"test_data": {"server": 948, "web": 123, "ios": 78}
}
}
Разработка на локальной машине
По умолчанию Loop не отправляет запросы на внутренние адреса: localhost, 127.0.0.0/8 и частные подсети. Чтобы разрешить их, системный администратор указывает адреса или подсети в Системная консоль > Окружение > Разработчик > Разрешить недоверенные внутренние соединения для (ServiceSettings.AllowedUntrustedInternalConnections), например 127.0.0.1 builds.internal 10.0.0.0/8.
Отладка
Ошибки запросов к URL обратного вызова записываются в журнал сервера. Настройки — в Системная консоль > Окружение > Ведение журнала: Включить отладку Webhook-ов (включено по умолчанию) и Уровень логирования в консоли.