Входящие вебхуки
Как одним HTTP-запросом опубликовать сообщение в канале Syncra: где взять адрес, что отправить, какие ответы и ограничения.
Входящий вебхук — это секретный адрес, привязанный к одному каналу. Ваш сервис отправляет на него POST-запрос с текстом, и бот публикует этот текст в канале. Ключ бота и заголовок авторизации для этого не нужны. Так в канал приходят уведомления из ваших систем: о сборках, оплатах и сбоях. Адрес создаёт владелец или администратор рабочего пространства: настройки рабочего пространства, вкладка «Боты», страница бота, раздел «Входящие вебхуки». Вебхук принадлежит боту, поэтому сначала нужен бот: Боты.
Как получить адрес
- Откройте настройки рабочего пространства, вкладку «Боты», и страницу нужного бота.
- В разделе «Входящие вебхуки» выберите канал в поле «Канал». Подходят открытые и закрытые каналы. Личные сообщения выбрать нельзя.
- Если нужно, заполните «Название (необязательно)», например «Оповещения из Grafana». Название помогает отличать вебхуки в списке.
- Нажмите «Создать вебхук». Бот сам вступит в выбранный канал.
- В строке вебхука появится адрес целиком. Скопируйте его кнопкой рядом.
Адрес выглядит так: 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, настройте подписки на события. Общий список ограничений собран на странице Что есть и чего нет.