Discord Webhook Полный гайд — настройка, код и паттерны

Что такое Discord Webhook?

Discord Webhook — это уникальный URL, через который любой внешний сервис может постить сообщения в конкретный Discord-канал без бота и без пользовательского аккаунта. URL содержит ID и токен — вместе они авторизуют HTTP-POST в Discord API от имени одного канала.

Механически webhook — это тонкий однонаправленный мост: HTTP POST внутрь, сообщение в Discord. Без логина, OAuth и gateway-соединения. Можно слать обычный текст, embed, файлы и даже интерактивные компоненты — из curl-однострочника или CI-пайплайна.

Типичный webhook URL выглядит так:

https://discord.com/api/webhooks/123456789012345678/aBcDeF...secret-token

Первый числовой сегмент — webhook ID (публичный). Второй — секретный токен; берегите как пароль. Любой с этим URL может постить в канал.

Webhook vs Bot — что выбрать

Webhook и бот пересекаются по возможности отправки сообщений, но разные по scope. Самый простой выбор: одностороннее уведомление или интерактив.

Берите webhook для push-уведомлений, deploy-алертов, scheduled-отчётов, RSS, GitHub-событий, мониторинга — любого one-way потока в Discord.

Берите бота для slash-команд, реакций, role-автоматизации, button-callback'ов, member-событий и всего, что Discord считает «interaction».

Production-сетапы часто комбинируют оба: webhook быстро шлёт уведомление, бот слушает кнопочные клики. Гибридный паттерн: интерактивные кнопки с ботом.

Создание Webhook URL

Нужно право Manage Webhooks в целевом канале (у владельцев и админов оно есть всегда). Процесс ~30 секунд:

1. Откройте Server Settings (стрелка рядом с названием сервера → Server Settings).
2. В левом сайдбаре нажмите Integrations.
3. Нажмите Webhooks → New Webhook.
4. Задайте имя, целевой канал и (опционально) аватар.
5. Нажмите Copy Webhook URL.

Этот URL — теперь ваш единственный credential. Любой с ним постит как webhook. Никогда не коммитьте в git, не вставляйте в публичный чат, не встраивайте в client-side JavaScript. Полный чек-лист — в разделе про безопасность.

Скриншоты и пошаговый разбор: Гайд по созданию Discord Webhook.

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

Простейший webhook-вызов — POST с JSON-телом и полем content. Через curl:

curl -X POST -H "Content-Type: application/json" \
     -d '{"content":"Hello from a webhook!"}' \
     "https://discord.com/api/webhooks/ID/TOKEN"

Discord возвращает 204 No Content при успехе, сообщение появляется в канале. Полная схема payload принимает:

• content — обычный текст до 2000 символов
• embeds — массив до 10 embed-объектов
• username — переопределить имя webhook на это сообщение
• avatar_url — переопределить аватар
• tts — text-to-speech (редко полезно)
• allowed_mentions — управление пингами (см. ниже)
• components — интерактивные кнопки и select-меню
• flags — bitfield (например, Components V2, suppress notifications)

За кодом на конкретном языке — раздел Примеры кода.

Embed — богатое форматирование

Embed — те самые цветные карточки с акцентной полосой слева. Поддерживают title, description (Markdown), URL, color, fields (key-value), thumbnail, image, footer, author и timestamp.

{
  "embeds": [{
    "title": "Build #2341 — passed",
    "description": "Все проверки зелёные ✓",
    "url": "https://example.com/builds/2341",
    "color": 5763719,
    "fields": [
      { "name": "Branch", "value": "main", "inline": true },
      { "name": "Длительность", "value": "2м 14с", "inline": true }
    ],
    "footer": { "text": "CI bot" },
    "timestamp": "2026-05-07T10:00:00.000Z"
  }]
}

Поле color — десятичное RGB-целое. Discord игнорирует hex-строки — конвертируйте #5865F2 → 5793266. Справка: Цвета Discord embed.

Полная справка по embed-объекту со всеми полями и ограничениями — гайд по embed builder. Или совсем не пишите JSON руками — используйте визуальный конструктор: drag-and-drop, готовый JSON копируется кнопкой.

Components V2 — современные layout

Components V2 — новая система layout сообщений, заменяющая embed для сложного контента. Вместо фиксированной структуры embed вы собираете сообщение из sections, text displays, media galleries, separators и containers — гораздо ближе к настоящему UI-фреймворку.

Чтобы использовать Components V2, в bitfield flags установите V2-флаг (1 << 15 = 32768) и передайте массив components с V2-типами вместо content/embeds.

Смешивать V2-компоненты с классическим embed в одном сообщении нельзя — выбираете один режим на сообщение. Гайд по Components V2 покрывает все типы с примерами; визуальный конструктор поддерживает оба режима.

Файлы и вложения

Загрузка файлов переключает body запроса с JSON на multipart/form-data. Добавьте form-поле payload_json с JSON-телом, затем поля files[0], files[1] и т.д.

curl -X POST \
  -F 'payload_json={"content":"Логи прикреплены"}' \
  -F 'files[0]=@./error.log' \
  "https://discord.com/api/webhooks/ID/TOKEN"

Файлы — до 25 МБ на вложение для серверов без Nitro. Чтобы вставить загруженную картинку в embed, сошлитесь на неё через attachment://filename в image.url. Полная справка: Отправка файлов через webhook.

Edit и Delete сообщений

Чтобы потом отредактировать или удалить webhook-сообщение, нужен его message ID. По умолчанию POST возвращает пустое тело — добавьте ?wait=true к URL, и Discord вернёт полный объект сообщения с id:

POST /api/webhooks/ID/TOKEN?wait=true
→ { "id": "987...", "content": "Hello", ... }

PATCH /api/webhooks/ID/TOKEN/messages/987...
{ "content": "Updated content" }

DELETE /api/webhooks/ID/TOKEN/messages/987...

Сохраните id, если редактируете между перезапусками процесса. Для сообщений в треде — ?thread_id=... на PATCH/DELETE URL. Подробно: Edit и delete webhook-сообщений.

Упоминания и allowed_mentions

Webhook-сообщения умеют пинговать пользователей (<@USER_ID>), роли (<@&ROLE_ID>) и @everyone / @here точно как обычные сообщения. По умолчанию каждое упоминание в content вызывает уведомление — включая те, что пришли из неотсанитайзенного user input.

Безопасный default — allowed_mentions с parse: []. Mention-синтаксис останется в тексте, но пинги не сработают:

{
  "content": "Hi @everyone, please check <@&123>",
  "allowed_mentions": { "parse": [] }
}

Дальше включаете нужные пинги через users: ["123"], roles: ["456"] или parse: ["roles"]. Полная матрица: Управление упоминаниями в webhook.

Треды и forum-каналы

Чтобы постить в существующий тред, добавьте ?thread_id=THREAD_ID к URL webhook. Чтобы создать новый пост в forum-канале, передайте в JSON-теле верхнеуровневое поле thread_name — Discord создаст пост, ваш content/embeds станет первым сообщением.

POST /api/webhooks/ID/TOKEN
{
  "thread_name": "Daily build report",
  "content": "Build #2341 ✅"
}

Edit/delete для сообщений в треде требуют тот же thread_id на URL. Подробно: Треды и forum-каналы.

Rate Limits и обработка 429

Webhook-ограничения per-route. Каждый ответ несёт заголовки X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset-After. Когда remaining = 0 — 429 Too Many Requests с Retry-After в секундах.

Консервативный бюджет одного webhook — примерно 5 запросов / 2 секунды (~30/мин в среднем). Кратковременные всплески выше — Discord очередует; длительные — 429.

Production-код должен:

• Уважать Retry-After на 429 (sleep, потом ретрай 1 раз)
• Трекать X-RateLimit-Remaining и сам тормозить до 0
• Использовать экспоненциальный backoff на 5xx
• Сериализовать «горячие» циклы через очередь или semaphore

И discord.js, и discord.py делают это автоматически. Для raw HTTP — гайд по rate limits с реализациями retry на Python и JavaScript.

Лимиты embed и payload

Discord жёстко контролирует посимвольные лимиты на каждое поле и общий потолок payload. Превышение — 400 Bad Request с кодом ошибки 50035:

Полные валидаторы на Python и TypeScript: cheat-sheet по лимитам embed.

Безопасность — защита webhook

Webhook URL — bearer credential. Любой с этим URL может:

• Постить произвольные сообщения, embed и файлы (с кастомным username/аватаром)
• Редактировать и удалять каждое сообщение, отправленное webhook
• Пинговать @everyone, если канал позволяет
• Спамить канал, пока вы не удалите webhook

Чек-лист закаливания:

1. Никогда не коммитьте URL в git. .env + .gitignore, GitHub Actions secrets или secret manager платформы.
2. Никогда не вставляйте в client-side JavaScript. DevTools браузера моментально утечёт.
3. Используйте server-side proxy, если webhook должен дёргаться из браузера — пусть бэк держит секрет и форвардит санитайзенные запросы.
4. Включите GitHub secret scanning — Discord webhook URL это распознаваемый паттерн; GitHub предупредит о случайном коммите.
5. Сразу ротируйте при утечке: удалите webhook в настройках Discord (это отзывает токен), создайте новый, обновите secret store.
6. Отключите @everyone на уровне канала, если webhook постит user-generated контент — в связке с allowed_mentions: { parse: [] }.

Полный incident response и proxy-паттерн с кодом: Гайд по безопасности Discord webhook.

Примеры кода по языкам

Берите гайд под ваш стек. Каждый покрывает send, embed, файлы, edit/delete и обработку rate-limit под конкретную экосистему.

Реальные паттерны

Webhook раскрывается в production в связке с устоявшимся паттерном. Самые частые:

Discohook vs Discord Webhook

Discohook много лет был каноничным визуальным конструктором webhook; не поддерживается с тех пор как автор приостановил работу. Discord Webhook (этот сайт) — современное продолжение: те же цели, актуальные фичи Discord, без регистрации, бесплатно навсегда.

Главные отличия:

• Components V2 — Discohook застрял на классических embed; мы поддерживаем оба режима.
• Bot integration — отправка через webhook ИЛИ через bot-токен с кастомными фичами.
• Активная разработка — новые фичи Discord появляются у нас в течение недель после релиза.
• Шаблоны и пресеты — changelog, status page, welcome — старт за секунды.
• Privacy — без аналитики, без трекинга, без сбора данных. Webhook URL не покидает ваш браузер.

Сравнение бок о бок: Discohook vs Discord Webhook и почему мы лучшая альтернатива Discohook.