РазделВходящие вебхуки

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

Как одним HTTP-запросом опубликовать сообщение в канале Syncra: где взять адрес, что отправить, какие ответы и ограничения.

Входящий вебхук — это секретный адрес, привязанный к одному каналу. Ваш сервис отправляет на него POST-запрос с текстом, и бот публикует этот текст в канале. Ключ бота и заголовок авторизации для этого не нужны. Так в канал приходят уведомления из ваших систем: о сборках, оплатах и сбоях. Адрес создаёт владелец или администратор рабочего пространства: настройки рабочего пространства, вкладка «Боты», страница бота, раздел «Входящие вебхуки». Вебхук принадлежит боту, поэтому сначала нужен бот: Боты.

Как получить адрес

  1. Откройте настройки рабочего пространства, вкладку «Боты», и страницу нужного бота.
  2. В разделе «Входящие вебхуки» выберите канал в поле «Канал». Подходят открытые и закрытые каналы. Личные сообщения выбрать нельзя.
  3. Если нужно, заполните «Название (необязательно)», например «Оповещения из Grafana». Название помогает отличать вебхуки в списке.
  4. Нажмите «Создать вебхук». Бот сам вступит в выбранный канал.
  5. В строке вебхука появится адрес целиком. Скопируйте его кнопкой рядом.

Адрес выглядит так: https://ai-syncra.ru/api/webhooks/whk_.... Часть whk_... и есть секрет: любой, кто знает адрес, может писать в канал. Храните его как пароль и не кладите в открытый код. Адрес остаётся в настройках, пока вебхук существует, так что его можно скопировать ещё раз.

У одного бота может быть несколько вебхуков. Каждый привязан к одному каналу.

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

POST /api/webhooks/:token

Публикует текст в канале, к которому привязан вебхук. Автор сообщения — бот.

Параметр адреса:

Параметр Тип Обязателен Описание
token string да Секретная часть адреса, начинается с whk_. Берите адрес целиком из настроек.

Тело запроса в формате JSON:

Поле Тип Обязательно Описание
text string да Текст сообщения, от 1 до 4000 символов.

Других полей у запроса нет. Остальные поля Syncra не читает. Заголовок Authorization не нужен.

curl -X POST "https://ai-syncra.ru/api/webhooks/whk_..." \
  -H "Content-Type: application/json" \
  -d '{"text":"Сборка 142 прошла"}'

Ответ 200 OK:

{
  "ok": true,
  "messageId": "..."
}

messageId — номер опубликованного сообщения. По нему бот может изменить или удалить это сообщение и ответить на него в ветке через API ботов: Сообщения в API ботов.

Ошибки

Тело ошибки — JSON с полем error. Текст в нём по умолчанию английский. Если запрос несёт заголовок Accept-Language: ru, известные тексты приходят по-русски, поэтому опирайтесь на статус, а не на текст.

Статус Тело Когда
400 {"error":"Invalid JSON"} Тело запроса не разбирается как JSON.
403 {"error":"Forbidden"} Запрос пришёл со страницы другого сайта: в нём есть заголовок Origin или Referer с чужим адресом.
404 {"error":"Not found"} Адрес неизвестен, вебхук удалён или бот выключен.
422 {"error":"Validation error","details":{...}} Поля text нет, оно пустое, длиннее 4000 символов или не строка.
429 {"error":"Too many requests"} Превышен лимит запросов на этот вебхук.

Пример ответа 422, когда в теле нет text:

{
  "error": "Validation error",
  "details": {
    "formErrors": [],
    "fieldErrors": {
      "text": ["Required"]
    }
  }
}

В fieldErrors ключ — имя поля, значение — список причин. Текст причин формирует библиотека проверки данных на сервере Syncra. Опирайтесь на статус и имя поля, а не на текст причины.

Ограничения

  • Не больше 60 запросов за 60 секунд на один вебхук. Отсчёт 60 секунд начинается с первого запроса. Запросы с ошибкой в теле тоже считаются.
  • В ответе 429 нет заголовков Retry-After и X-RateLimit-*. Подождите до минуты и повторите.
  • Отправляйте запрос с сервера. Запрос со страницы в браузере на другом сайте не пройдёт.
  • Вебхук публикует только текст. Вложений в запросе нет.
  • Сообщение всегда новое. Ответить в ветку через вебхук нельзя.
  • Имя и аватар у сообщения — от бота. Задать свои в запросе нельзя.
  • @channel и @here в тексте никого не оповещают.
  • Вебхук пишет в один канал, который выбран при создании. Сменить канал нельзя: создайте новый вебхук.
  • Вебхук не пишет в личные сообщения.

Отключить или удалить вебхук

Чтобы закрыть адрес навсегда, нажмите «Удалить» в строке вебхука и подтвердите. Запросы на этот адрес сразу начнут получать 404. Вернуть удалённый адрес нельзя: создайте новый вебхук и замените адрес в своём сервисе.

Чтобы остановить всё разом, выключите переключатель «Бот включён» на странице бота. Пока бот выключен, его вебхуки отвечают 404, Syncra не принимает ключи бота и не отправляет события его подпискам.

Когда вебхука мало

Если сервису нужно отвечать в ветках, прикладывать файлы, читать сообщения или писать в личные сообщения, используйте ключ бота и API ботов:

Если нужно, наоборот, узнавать о событиях в Syncra, настройте подписки на события. Общий список ограничений собран на странице Что есть и чего нет.