Вебхуки приложения

Вебхук приложения это URL для конкретного канала, на который ваш CI-раннер, система мониторинга или внешний сервис может отправить POST, чтобы опубликовать сообщение в канале GameVox. Сессия шлюза не нужна. Сообщения публикуются от имени пользователя-бота, с его аватаром и именем.

Ограничения

50 вебхуков на приложение.
Название: 1–80 символов.
Содержимое: 1–4000 символов на сообщение.
Один вебхук = один канал. Для создания вебхука нужно право manage_server на сервере этого канала.

Формат токена

WH.{префикс из 8 символов}.{случайные данные base64}

пример: WH.aB7xZ2k1.q9F7v1NkN3J2Wm8L6PpV5cU0Yr1zQbXa

Полный токен показывается ровно один раз, при создании. Мы храним только хеш bcrypt, а также префикс и последние 4 символа для отображения. Если вы потеряли токен, удалите вебхук и создайте новый.

Создание вебхука (портал)

Откройте приложение → вкладку Вебхуки → Новый вебхук. Выберите сервер, которым вы можете управлять, выберите канал, дайте вебхуку название. В окне показа будут полный токен и готовый к вставке URL выполнения. Скопируйте его, прежде чем закрыть окно: портал больше никогда его не покажет.

Эндпоинты

Два режима аутентификации: токен бота для управления, токен в URL для выполнения.

Аутентификация токеном бота (управление)

GET    /channels/{channel.id}/webhooks
POST   /channels/{channel.id}/webhooks
GET    /guilds/{guild.id}/webhooks
GET    /webhooks/{webhook.id}
PATCH  /webhooks/{webhook.id}
DELETE /webhooks/{webhook.id}

Аутентификация токеном в URL (выполнение + изменение)

POST   /webhooks/{webhook.id}/{token}
GET    /webhooks/{webhook.id}/{token}
PATCH  /webhooks/{webhook.id}/{token}
DELETE /webhooks/{webhook.id}/{token}
PATCH  /webhooks/{webhook.id}/{token}/messages/{message.id}
DELETE /webhooks/{webhook.id}/{token}/messages/{message.id}

Для маршрутов с токеном в URL заголовка Authorization нет. Токен в пути URL и есть аутентификация. Обращайтесь с URL как с секретом.

Запрос выполнения

Тело JSON:

POST https://api.gamevox.com/webhooks/{webhook.id}/{token}
Content-Type: application/json

{
  "content": "Сборка #4811 прошла на production.",
  "embeds": [
    {
      "title": "CI зелёный",
      "url": "https://ci.example.com/builds/4811",
      "description": "42 теста, 0 ошибок.",
      "color": 3066993
    }
  ]
}

Тело multipart/form-data (для вложений):

Content-Type: multipart/form-data; boundary=xyz

--xyz
Content-Disposition: form-data; name="payload_json"

{ "content": "См. скриншот", "embeds": [ ... ] }
--xyz
Content-Disposition: form-data; name="files[0]"; filename="crash.png"
Content-Type: image/png

...binary...
--xyz--

Ответ (для обоих типов содержимого):

{
  "id": "1199283740192847400",
  "channel_id": "1199283740192847000",
  "content": "Сборка #4811 прошла на production.",
  "embeds": [ ... ],
  "attachments": [ ... ],
  "timestamp": "2026-05-21T15:42:09Z"
}

Что поддерживается

Содержимое: обычный текст, 1–4000 символов.
Эмбеды: полная структура эмбеда Discord (title, description, url, color, timestamp, footer, image, thumbnail, author, fields). Можно несколько эмбедов в одном сообщении.
Вложения: загружайте файлы через multipart/form-data с частью payload_json; ответ содержит URL CDN.
Ответ на сообщение: передайте message_reference в payload_json.
?wait=true: подразумевается; ответ всегда содержит итоговое сообщение.
Изменение / удаление: PATCH / DELETE на /webhooks/{id}/{token}/messages/{message.id} работают как в Discord.
Переопределение имени / аватара: не поддерживается. Сообщения всегда публикуются от имени пользователя-бота приложения.

Ошибки

401: токен отсутствует, имеет неверный формат или не совпадает.
404: вебхук удалён или такого id не существует.
400: пустое content без эмбедов и вложений или content длиннее 4000 символов.
405: метод не поддерживается на этом маршруте.
413: вложение превышает ограничение размера файла.

Смена токена

В v1 нет эндпоинта для смены токена на месте. Удалите вебхук и создайте новый. Старый токен перестаёт работать сразу после удаления (путь выполнения исключает мягко удалённые строки).

Отличия от Discord

Вебхуки принадлежат приложению, а не администратору сервера. Удаление канала не удаляет строку вебхука; следующее выполнение вернёт 404, потому что при поиске не найдётся канал.
Нет переопределения username / avatar_url в запросе. Отправитель всегда пользователь-бот.
Лимит вебхуков на канал не применяется; лимит действует на приложение (50).
Аутентификация проверяется через bcrypt, поэтому сравнение токена намеренно медленное. Не заваливайте эндпоинт запросами в плотном цикле.
Собственные серверы: вебхуки не маршрутизируются на собственные серверы. Все эндпоинты вебхуков возвращают 404 для серверов на собственном хостинге. См. документацию по собственным серверам.

← Назад к документации