Вебхуки

Вебхуки — простейший способ постить сообщения в каналы Lolka. Тебе не нужен бот и не нужно получать токен OAuth: достаточно создать вебхук в настройках канала и отправлять HTTP POST на секретный URL.

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

Вебхук принадлежит конкретному текстовому каналу внутри сервера. Создавать и редактировать вебхуки может любой участник, у которого есть право Управление вебхуками на этом канале.

• Открой настройки канала → вкладка «Интеграции» → «Вебхуки».
• Нажми «Новый вебхук», задай имя (1–80 символов) и, при желании, аватар.
• Скопируй URL — его и нужно будет использовать для отправки сообщений.

Также можно управлять вебхуками на уровне сервера (страница «Интеграции сервера»): там видно все вебхуки по всем каналам, куда у тебя есть доступ.

Объект вебхука

Когда вебхук отдаётся наружу (например, при создании), он имеет такую структуру:

Пример

{
  "id": 7234876123234,
  "type": 1,
  "channel_id": 881723489234,
  "server_id": 771223489001,
  "name": "Captain Hook",
  "avatar_url": "https://cdn.lolka.app/avatars/webhook/..../256.webp",
  "token": "NzIzNDg3NjEyMzIzNA.q8F2C...",
  "url": "https://lolka.app/api/webhooks/7234876123234/NzIzNDg3NjEyMzIzNA.q8F2C...",
  "user": {
    "id": 100000000001,
    "username": "nikita",
    "display_name": "Никита",
    "avatar_url": "https://cdn.lolka.app/avatars/user/..../128.webp"
  }
}

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

Постит сообщение в канал вебхука. Аутентификация — самим token в URL; ни сессионный cookie, ни Authorization header не нужны.

Query-параметры

Тело запроса (JSON)

Пример

curl -X POST \
  "https://lolka.app/api/webhooks/7234876123234/NzIzNDg3NjEyMzIzNA.q8F2C..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Привет из CI! Сборка #123 прошла :)",
    "username": "build-bot",
    "avatar_url": "https://example.com/bot.png"
  }'

Ответ

При wait=true (по умолчанию) в ответ приходит созданное сообщение в стандартном формате канальных сообщений:

{
  "id": 98234876234,
  "channel_id": 881723489234,
  "author": {
    "id": 7234876123234,
    "username": "build-bot",
    "is_webhook": true,
    "webhook_id": 7234876123234
  },
  "content": "Привет из CI! Сборка #123 прошла :)",
  "created_at": "2026-04-22T12:00:03Z"
}

Отправка файлов

Чтобы прикрепить файлы, отправляй запрос как multipart/form-data. Текстовые параметры передавай как обычные поля формы, а файлы — полями files[0], files[1] и т.д.

• Максимум 10 файлов за один запрос.
• До 10 MB на файл.
• Поддерживаемые типы: image/*, video/*, audio/*, application/pdf, text/plain.

curl -X POST \
  "https://lolka.app/api/webhooks/7234876123234/NzIzNDg3NjEyMzIzNA.q8F2C..." \
  -F "content=Отчёт за день во вложении" \
  -F "files[0]=@./report.pdf"

Rich-embeds

Rich-embed — это блок внутри сообщения с заголовком, описанием, картинками, цветной полосой, полями и футером. Передаётся как элемент массива embeds в теле запроса. Все поля опциональные — достаточно, например, одного title.

Объект embed

Вложенные объекты

embed.author

embed.footer

embed.image / embed.thumbnail

embed.fields[]

Пример

Полный payload с embed:

{
  "content": "Новый релиз выкатили 🚀",
  "embeds": [{
    "title": "build #1247 · production",
    "description": "**Успешно** задеплоено в прод.\n\n> Все smoke-тесты зелёные",
    "url": "https://ci.example.com/builds/1247",
    "color": 3066993,
    "timestamp": "2026-04-22T18:00:00.000Z",
    "author": {
      "name": "ci-bot",
      "url": "https://ci.example.com",
      "icon_url": "https://ci.example.com/logo.png"
    },
    "footer": {
      "text": "env: prod · v1.2.3",
      "icon_url": "https://ci.example.com/favicon.png"
    },
    "thumbnail": {
      "url": "https://ci.example.com/status-ok.png"
    },
    "image": {
      "url": "https://ci.example.com/builds/1247/chart.png"
    },
    "fields": [
      { "name": "Ветка", "value": "main", "inline": true },
      { "name": "Коммит", "value": "`a1b2c3d`", "inline": true },
      { "name": "Длительность", "value": "4m 12s", "inline": true }
    ]
  }]
}

В ответе сервер вернёт embed обратно и дополнит поля картинок:

"embeds": [{
  "type": "rich",
  "title": "build #1247 · production",
  "description": "**Успешно** задеплоено в прод.\n\n> Все smoke-тесты зелёные",
  "url": "https://ci.example.com/builds/1247",
  "color": 3066993,
  "timestamp": "2026-04-22T18:00:00Z",
  "author": {
    "name": "ci-bot",
    "url": "https://ci.example.com",
    "icon_url": "https://ci.example.com/logo.png",
    "proxy_icon_url": "https://cdn.lolka.app/embeds/a1b2c3d4....webp"
  },
  "footer": {
    "text": "env: prod · v1.2.3",
    "icon_url": "https://ci.example.com/favicon.png",
    "proxy_icon_url": "https://cdn.lolka.app/embeds/e5f6g7h8....webp"
  },
  "thumbnail": {
    "url": "https://ci.example.com/status-ok.png",
    "proxy_url": "https://cdn.lolka.app/embeds/f0e1d2c3....webp",
    "width": 200,
    "height": 200
  },
  "image": {
    "url": "https://ci.example.com/builds/1247/chart.png",
    "proxy_url": "https://cdn.lolka.app/embeds/11223344....webp",
    "width": 800,
    "height": 420
  },
  "fields": [...]
}]

Лимиты embed

При нарушении любого лимита сервер отвечает 400 Bad Request с описанием ошибки.

Slack- и GitHub-совместимые эндпоинты

Чтобы не переписывать существующие интеграции со Slack и GitHub, Lolka принимает их нативные форматы и сама конвертирует их в сообщение канала.

Принимает payload Slack Incoming Webhook (text, attachments, blocks в базовом виде). Достаточно просто подставить URL Lolka-вебхука вместо slack-hooks.

Принимает payload GitHub-вебхука. Обязателен заголовок X-GitHub-Event (например push, pull_request, issues) — по нему мы выбираем шаблон сообщения.

Управление сообщениями вебхука

У каждого отправленного сообщения можно получить его текущее состояние, отредактировать текст или удалить его. Аутентификация такая же — token вебхука в URL.

Получить сообщение

Возвращает сообщение в том же формате, что и ответ на POST.

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

Меняет содержимое сообщения. Все поля опциональные.

{
  "content": "Исправленный текст",
  "embeds": [{
    "title": "Обновлено",
    "description": "Статус изменился",
    "color": 16711680
  }]
}

Удалить сообщение

При успехе возвращает 204 No Content.

Лимиты

При превышении лимитов возвращается 429 Too Many Requests с телом { "code": "WEBHOOK_RATE_LIMIT_EXCEEDED" }. Рекомендуется добавлять экспоненциальный backoff при ретраях.

Безопасность

• Токен в URL = полный доступ к вебхуку. Любой, у кого есть ссылка, сможет постить сообщения в канал. Не коммить URL в публичные репозитории, не логируй его, не передавай в client-side-коде браузера.
• Если токен утёк — регенерируй его в настройках канала. Старый URL сразу перестанет работать.
• Мы не подписываем запросы сервером и не отдаём ни X-Signature, ни X-Timestamp — единственным секретом является сам токен.
• Все внешние URL (avatar_url, icon_url, image.url и т.д.) должны быть по https:// и доступны из интернета.