Когда нужен вебхук
Вебхук подходит для уведомлений о сборке, событии внешнего сервиса или обновлении. Он отправляет сообщения в заранее выбранный текстовый канал. Для чтения сообщений, команд, кнопок и реакции на события используйте бота.
Создание
Откройте настройки текстового канала → «Вебхуки · автоматические сообщения». Создать и удалить вебхук может участник с MANAGE_CHANNELS. Сохраните выданные path и token: секрет показывается один раз, в базе хранится его хеш.
| Аккаунт-токен | Операция |
|---|---|
| GET /api/channels/:channelId/webhooks | Список вебхуков. |
| POST /api/channels/:channelId/webhooks | {name, author_name?, avatar_url?} → 201 {webhook, token, path}. |
| DELETE /api/channels/:channelId/webhooks/:id | Удаление вебхука. |
Адрес и идентификатор относятся к API хоста канала. Вебхуки не предназначены для ЛС, групп и пабликов.
Отправка
POST /api/webhooks/:id/execute
Authorization: Bearer <WEBHOOK_TOKEN>
Content-Type: application/json
{ "embeds": [{
"title": "Сборка готова",
"description": "Версия доступна для проверки.",
"color": 5793266,
"fields": [{ "name": "Статус", "value": "Готово", "inline": true }]
}] }Также допускается {"content":"Текст"} до 2000 символов. До 10 карточек и 6000 символов суммарно. При content вместе с embeds текст занимает одну карточку. Успешный ответ 201 содержит id сообщения и channel_id. Канал задаётся в настройках, а не телом запроса.
Лимиты и безопасность
- Один принятый запрос раз в 2 секунды на вебхук. При 429 используйте Retry-After: 2.
- Автор и аватар задаются при создании, а не произвольным отправителем. Карточка помечается «Вебхук».
- Права создателя проверяются при отправке. Потеря прав может привести к 403.
- При неизвестном результате запроса не повторяйте его без проверки: идемпотентность не реализована.
- Передавайте секрет в Authorization, не в URL. При утечке удалите вебхук и создайте новый.
- Избегайте персональных данных в уведомлениях и URL изображений внешних сервисов.