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

Входящий вебхук — это уникальный адрес. Внешняя система отправляет на него HTTP POST-запрос с JSON, а Loop публикует сообщение в канал. Подходит для уведомлений из CI/CD, мониторинга, CRM и любых скриптов.

Создание вебхука

1. Откройте Главное меню > Интеграции > Входящие вебхуки и нажмите Добавить входящий Webhook.

2. Заполните Заголовок (до 64 символов) и при необходимости Описание (до 500 символов).

3. Выберите Канал, куда будут приходить сообщения. Для частного канала вы должны быть его участником.

4. (Необязательно) Включите Прикрепить к этому каналу — тогда вебхук сможет писать только в выбранный канал.

5. (Необязательно) Задайте Имя пользователя и Изображение профиля для сообщений. Эти поля появляются, если администратор разрешил интеграциям их переопределять (см. ниже).

6. (Необязательно) Включите Получать уведомления на реакции — вам будут приходить уведомления о реакциях на сообщения вебхука.

7. Нажмите Сохранить и скопируйте адрес вебхука:

   https://your-loop-server.ru/hooks/xxx-generatedkey-xxx

Нет раздела «Интеграции»?

Вебхуками управляют пользователи с разрешением Управление входящими вебхуками — по умолчанию это системные администраторы и администраторы команд. Сами входящие вебхуки включаются в Системная консоль > Интеграции > Управление интеграцией > Разрешить входящие вебхуки (включено по умолчанию).

warning

Не публикуйте адрес вебхука: любой, кто его знает, сможет отправлять сообщения в ваш Loop.

Отправка сообщения

Отправьте POST-запрос с JSON в теле:

POST /hooks/xxx-generatedkey-xxx HTTP/1.1
Host: your-loop-server.ru
Content-Type: application/json

{"text": "Привет! Это первое сообщение.\nА это вторая строка. :tada:"}

То же самое с помощью curl:

curl -i -X POST -H 'Content-Type: application/json' \
  -d '{"text": "Привет! Это первое сообщение.\nА это вторая строка. :tada:"}' \
  https://your-loop-server.ru/hooks/xxx-generatedkey-xxx

При успехе Loop ответит 200 OK с телом ok.

Формат тела запроса

Content-Type	Как передать данные
application/json или не указан	JSON в теле запроса
application/x-www-form-urlencoded	JSON в поле payload, например payload={"text": "Привет"}. Так отправляют интеграции, написанные для Slack
multipart/form-data	Параметры как поля формы (text, channel, username и т. д.)

Параметры

Параметр	Описание	Обязательный
text	Текст сообщения с поддержкой Markdown. Упоминания @username, @channel и @here работают как в обычных сообщениях.	Да, если нет attachments
channel	Канал вместо канала по умолчанию. Указывается имя канала из URL (town-square), а не отображаемое название. @username — личное сообщение пользователю. Можно добавить # в начале, как в Slack.	Нет
username	Имя отправителя вместо заданного в вебхуке. Работает, если разрешено переопределение имён.	Нет
icon_url	Адрес изображения профиля отправителя. Работает, если разрешено переопределение изображений.	Нет
icon_emoji	Эмодзи вместо изображения профиля (имя с двоеточиями или без), важнее icon_url. Работает, если разрешено переопределение изображений.	Нет
attachments	Вложения для расширенного оформления: цвет, поля, изображения, кнопки.	Да, если нет text
type	Тип сообщения, обычно для плагинов. Должен начинаться с custom_. При передаче attachments игнорируется.	Нет
props	Произвольные данные сообщения в JSON — их могут читать другие интеграции через REST API. Ключи from_webhook, override_username, override_icon_url и webhook_display_name задаёт сам Loop. Про ключ card — ниже.	Нет
priority	Приоритет сообщения: объект с полем priority (important или urgent) и необязательными requested_ack и persistent_notifications.	Нет

Куда можно отправить сообщение

• В любой публичный канал команды, в которой создан вебхук.
• В частный канал, если создатель вебхука — его участник.
• Личное сообщение пользователю: "channel": "@username". Оно придёт в личную переписку между создателем вебхука и этим пользователем. Можно указать и своё имя — сообщение придёт вам самим.
• В личную переписку двух других пользователей — по имени канала из их ID через два подчёркивания: "channel": "6w41z1q367dujfaxr1nrykr5oc__94dzjnkd8igafdraw66syi1cde". Сработает, только если у создателя вебхука есть доступ к этому каналу (например, он системный администратор).

Если у вебхука включено Прикрепить к этому каналу, сообщения в другие каналы отклоняются.

Пример с несколькими параметрами

POST /hooks/xxx-generatedkey-xxx HTTP/1.1
Host: your-loop-server.ru
Content-Type: application/json

{
  "channel": "town-square",
  "username": "test-automation",
  "icon_url": "https://example.ru/icon.png",
  "text": "#### Результаты тестов за 27 июля\n@channel проверьте упавшие тесты.\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) |"
}

Результат в канале:

Дополнительная информация в карточке

Если передать Markdown в поле card объекта props, рядом со временем сообщения появится значок информации. По нажатию справа откроется панель с содержимым card.

{
  "channel": "town-square",
  "username": "sales-bot",
  "text": "#### Новая сделка!",
  "props": {
    "card": "Информация о сделке:\n\n[Открыть в CRM](https://crm.example.ru/deal/42)\n\n- Менеджер: **Иван Петров**\n- Сумма: **300 000 ₽**"
  }
}

Переопределение имени и изображения

По умолчанию сообщения вебхука публикуются от имени его создателя с меткой БОТ. Чтобы интеграции могли подставлять своё имя и изображение, системный администратор включает в Системная консоль > Интеграции > Управление интеграцией:

• Разрешить интеграциям переопределять имена (EnablePostUsernameOverride, по умолчанию выключено);
• Разрешить интеграциям переопределять иконки изображений профилей (EnablePostIconOverride, по умолчанию выключено).

Если переопределение имён включено, а имя не задано ни в вебхуке, ни в запросе, сообщение будет подписано webhook. Метка БОТ показывается всегда — это защита от фишинга.

Совместимость со Slack

Интеграции, написанные для Slack, обычно работают без изменений. Loop автоматически преобразует разметку Slack:

• <https://loop.ru/> — ссылка;
• <https://loop.ru/|здесь> — ссылка с текстом;
• <@USER_ID> — упоминание пользователя;
• <!channel>, <!here>, <!all> — упоминание канала.

Ограничения совместимости:

1. <#CHANNEL_ID> не превращается в ссылку на канал.
2. <!everyone> и <!group> не поддерживаются.
3. Параметры mrkdwn, parse и link_names игнорируются: Loop всегда обрабатывает Markdown и упоминания.
4. Жирный текст пишется как **bold**, а не *bold*.

GitLab

В GitLab можно использовать встроенную интеграцию со Slack: в настройках проекта откройте интеграцию Slack notifications, вставьте адрес входящего вебхука Loop, поле канала оставьте пустым и сохраните.

Советы

1. Сообщение длиннее 16 383 символов Loop разобьёт на несколько последовательных сообщений.
2. Вебхук можно вызывать из любого языка или инструмента, который умеет отправлять HTTP POST.
3. Для сообщений с кнопками и полями используйте вложения.

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

При ошибке Loop возвращает HTTP-код ошибки и JSON с описанием в поле message, а также пишет её в журнал сервера. Настройки журнала — в Системная консоль > Окружение > Ведение журнала:

• Включить отладку Webhook-ов — включено по умолчанию;
• чтобы в журнал попадало и тело входящих запросов, установите Уровень логирования в консоли в DEBUG.

Частые ошибки:

Ошибка	Причина
Не удалось найти канал	Канала из параметра channel нет в команде вебхука. Проверьте имя канала.
Не удалось найти пользователя	Пользователя из "channel": "@username" не существует.
Невозможно разобрать входящие данные	Некорректный JSON: лишние кавычки, запятые, неэкранированные переносы строк.
Текст не задан	Нет ни text, ни attachments.
Несоответствующие права канала	Создатель вебхука не состоит в частном канале из параметра channel.
Этому вебхуку не разрешено публиковать сообщения на запрошенном канале	У вебхука включено Прикрепить к этому каналу.
Входящие вебхуки отключены системным администратором	Выключен параметр Разрешить входящие вебхуки.
Неверный вебхук	Вебхук удалён или адрес скопирован с ошибкой.

В Windows curl часто выдаёт curl: (3) [globbing] unmatched close brace/bracket из-за одинарных кавычек вокруг JSON. Используйте двойные кавычки и экранируйте внутренние: -d "{\"text\": \"Привет\"}".