Алерты Discord для сокращателя URL: настройка Telegram, payload-структуры, типичные проблемы

Если короткая ссылка начинает отдавать 404 в три часа ночи, вы хотите получить алерт там, где уже дежурит ваш on-call. Для большинства инженерных команд это Discord; для ops- и growth-команд в Европе - нередко Telegram. Elido поставляет Beta-интеграции для обоих. В этой статье разберём, что и куда вставлять, какой JSON приходит на другой конец, и три сценария сбоев, которые подстерегают команды в первую неделю.

Два факта сразу. Первый: оба коннектора работают исключительно через вставку токена. Вы генерируете webhook URL или токен бота в UI провайдера, вводите его в Elido - и интеграция активна. Мы ничего не настраиваем автоматически на стороне Discord или Telegram: их API не предоставляют такой возможности. Второй: каждый алерт генерируется тем же event bus, который обслуживает функцию webhooks, поэтому контракты payload стабильны и задокументированы.

Почему эти два - Beta, а не Live

Каталог интеграций Elido присваивает статус Live тогда, когда одним кликом мы можем выполнить три действия: зарегистрировать ресурс провайдера, назначить нужные scope-ы и удалить всё при отключении. Notion, Linear и Pipedrive соответствуют этому критерию, потому что предоставляют OAuth и API для управления ресурсами.

Discord-вебхуки и Telegram-боты - нет. Webhooks API Discord требует пользователя-бота с разрешением Manage Webhooks в конкретном канале; управляемого нами flow согласия попросту не существует. Telegram ещё сложнее: BotFather - это чат-интерфейс без машиночитаемой выдачи токенов. Поэтому мы просим вас потратить 90 секунд на настройку у провайдера, а всё остальное берём на себя. Токен хранится в нашем хранилище с конвертным шифрованием и никогда не покидает webhook-диспетчер api-core.

Значок Beta означает: «работает, payload-ы стабильны, но UX подключения/отключения требует одного лишнего шага». Если вам нужен автопровижн уже сегодня, Slack имеет статус Live и работает на том же pipeline трансформеров.

Пошаговая настройка: начинаем с Discord

В Discord откройте нужный канал, нажмите на иконку шестерёнки и выберите Интеграции -> Вебхуки -> Новый вебхук. Дайте ему имя вроде elido-alerts, при желании загрузите аватар Elido из /blog/covers и скопируйте URL вебхука. Он выглядит так:

https://discord.com/api/webhooks/123456789012345678/AbCdEf-tokenstring

Этот URL - секрет. Любой, кто его получит, сможет постить в ваш канал. Обращайтесь с ним как с паролем.

В Elido перейдите в Настройки рабочего пространства -> Интеграции -> Discord. Вставьте URL, выберите типы событий в мультиселекте (broken_link, click_threshold, scan_failure, redirect_chain_change, qr_scan_anomaly) и сохраните. Форма сначала отправляет синтетическое тестовое событие; если Discord вернёт что-либо, кроме 204, сохранение не выполнится и вы увидите ошибку прямо в форме.

Telegram настраивается в два шага. Откройте чат с BotFather, выполните /newbot, придумайте имя и скопируйте токен. Он выглядит как 7891234567:AAH-tokenstring. Затем добавьте бота в чат, куда хотите получать алерты (личный чат, группа или канал), и отправьте любое сообщение. В Elido вставьте токен, нажмите «Найти чаты», выберите нужный из списка видимых боту чатов и сохраните.

Шаг «Найти чаты» выполняет однократный вызов getUpdates Telegram для перечисления chat ID, которые видел ваш бот. Если список пуст - бот добавлен, но не получил ни одного сообщения. Отправьте ему любое сообщение и повторите попытку.

Реальная структура payload

Именно здесь большинство туториалов «алерты в чат» начинают говорить общими словами. Вот что на самом деле приходит.

Для Discord мы отправляем один embed на событие, а не устаревшую строку content. Трансформер в services/api-core/internal/webhooks/delivery/transformers.go формирует следующую структуру:

{
  "username": "Elido",
  "embeds": [
    {
      "title": "Broken link detected",
      "description": "https://elido.me/launch -> 404 Not Found",
      "color": 15548997,
      "timestamp": "2026-06-04T09:14:22.000Z",
      "fields": [
        { "name": "Slug", "value": "launch", "inline": true },
        { "name": "Workspace", "value": "acme-prod", "inline": true },
        { "name": "Status", "value": "404", "inline": true },
        { "name": "First seen", "value": "2026-06-04 09:13:11 UTC" },
        { "name": "Last 5 redirects", "value": "blocked since 09:13:11" }
      ],
      "footer": { "text": "Elido alerts - broken_link" },
      "url": "https://elido.app/links/launch"
    }
  ]
}

Целое число color - это десятичное значение hex-кода. Мы используем четыре уровня важности: info 3447003 (синий), success 2280516 (зелёный), warn 15844367 (янтарный), error 15548997 (красный). Подробнее об этом маппинге чуть ниже.

Telegram работает иначе. Мы используем parse_mode: "HTML", потому что Markdown V2 требует экранирования около десятка символов и быстро становится нечитаемым. Вызов sendMessage выглядит так:

{
  "chat_id": -1001234567890,
  "parse_mode": "HTML",
  "disable_web_page_preview": true,
  "text": "<b>Broken link detected</b>\n<code>elido.me/launch</code> -> 404\n\nSlug: <code>launch</code>\nWorkspace: <code>acme-prod</code>\nFirst seen: 2026-06-04 09:13:11 UTC\n\n<a href=\"https://elido.app/links/launch\">Open in Elido</a>"
}

Мы устанавливаем disable_web_page_preview в true, чтобы чат не раздувался при разворачивании превью URL алерта. Превью ссылок в дежурном треде только мешают.

Оба транспорта повторяют попытки с одинаковым backoff-ом: 1с, 5с, 30с, 5мин, 30мин. После пяти неудач интеграция автоматически приостанавливается и отправляется письмо на почту. Каждая попытка логируется в ClickHouse и доступна через руководство по observability.

Маппинг уровня важности на цвет

Цвет - единственный сигнал, который пользователи Discord видят с первого взгляда. Мы выбрали четыре уровня важности и строго соблюдаем их во всех интеграциях с поддержкой цвета:

• info (#3B82F6, синий) - новая ссылка создана через API, первое сканирование назначения, опубликована bio-страница. Не требует действий, просто информация.
• success (#22C55E, зелёный) - link checker восстановился, сертификат обновлён для кастомного домена, достигнут порог конверсии.
• warn (#F59E0B, янтарный) - скорость кликов в 3 раза выше 7-дневного базового значения, цепочка редиректов выросла с 2 до 4 хопов, скорость QR-сканирований упала на 80%. Стоит посмотреть.
• error (#EF4444, красный) - broken_link, scan_failure (Google Safe Browsing пометил ваш целевой URL), TLS кастомного домена истёк, webhook-диспетчер сдался после 5 попыток.

Telegram не рендерит цвета, поэтому в начало каждого сообщения мы добавляем эмодзи, соответствующий уровню: синий ромб, зелёная галочка, жёлтое предупреждение, красный крест. Та же семантика, другой транспорт. Чтобы отфильтровать Telegram-алерты в клиенте только до красных событий, ищите крест в тексте сообщения.

Типичные сценарии сбоев (и как их распознать)

В продакшене возникают три проблемы. Их легко устранить, если знать, что искать.

Rate limit Discord на активном вебхуке. Discord ограничивает каждый webhook URL до 50 запросов в секунду и примерно 30/мин в устойчивом режиме. Подключите вебхук к каждому click_threshold вирусной кампании - и вы его достигнете. Симптомы: алерты приходят пачками с задержкой 30-60 секунд, ответы 429 в логе интеграции. Решение: включите throttle per-event (по умолчанию выключен), чтобы события, возникшие в течение 10-секундного окна, объединялись в один embed.

Режим конфиденциальности Telegram-бота. Режим конфиденциальности включён по умолчанию для новых ботов и влияет только на то, какие сообщения бот может читать в группах. Исходящие вызовы sendMessage он не затрагивает. Настоящий подводный камень: когда вы добавляете бота в группу, Telegram требует, чтобы бот получил хотя бы одно сообщение, прежде чем getUpdates вернёт этот chat_id. Если «Найти чаты» возвращает пустой список, отправьте боту любое сообщение и повторите попытку. Для каналов (не групп) добавьте бота как администратора с правом публикации - предварительное сообщение не нужно.

Ротация токена. Оба транспорта хранят секрет в зашифрованном виде через слой конвертного шифрования из ADR-0036. Открытый текст никогда не попадает в Postgres или логи. Когда токен утекает (скриншот в Slack, запись в audit log Discord, которой там не должно быть), ротация - это два клика: отзыв у провайдера, вставка нового значения в Elido. Строка интеграции, фильтры событий и история ClickHouse остаются нетронутыми, потому что привязаны к UUID интеграции, а не к секрету.

Когда выбирать что

Если ваша команда живёт в Discord - используйте Discord. Формат embed богаче, inline-поля отображаются предсказуемо на десктопе и мобайле, а цветовое обозначение важности достаётся бесплатно.

Если ваша команда в Telegram (характерно для европейских ops-команд, команд разработчиков в Восточной Европе и продуктов, связанных с крипто) - используйте Telegram. API getUpdates и sendMessage предельно прост, а HTML-режим закрывает 95% потребностей форматирования.

Если нужно оба - используйте оба. Каждая интеграция - отдельная строка с собственным фильтром событий, поэтому вы можете направлять события error-важности в Discord, а предупреждения - в Telegram-группу для «фонового шума». Такую схему используют несколько наших клиентов.

Для всего, что за пределами чата - обновления CRM, маркетинговая автоматизация, BI-пайплайны - правильными инструментами являются Zapier и API вебхуков. Чат - для людей, реагирующих на события. Вебхуки - для систем, реагирующих на события.

Для чего не стоит их использовать

Не используйте Discord или Telegram как единственный монитор link-rot. Чат эфемерен. Если алерт промелькнул во время насыщенного запуска, вы его не найдёте. Используйте чат как высокосигнальный слой поверх нормального observability-стека: link checker Elido для синтетических проверок, Datadog или Sentry для трейсов, и чат - для событий, которые человек действительно должен увидеть.

Не включайте персональные данные в payload алертов. Стандартный payload содержит slug ссылки и ID рабочего пространства - никогда IP клика или идентификатор посетителя. Если вы добавляете пользовательские метаданные через API и они содержат личные данные, они окажутся в истории чата Discord или Telegram. Ни один из этих провайдеров не входит в список DPA большинства компаний. Ограничивайтесь операционными данными.

Что в планах

Автоматический провижн для Discord возможен, если мы перейдём на модель Discord-бота вместо потребителя вебхука. Прототип готов. Ключ в том, чтобы дать пользователям возможность предоставить боту Elido доступ к каналу через OAuth-подобный consent flow, после чего мы создадим вебхук на стороне сервера. В план следующего квартала это не входит, но переведёт Discord в Live.

Для Telegram чистого пути нет. BotFather - интерфейс только для людей, поэтому полный автоматический провижн невозможен. Обновления планов доступны в changelog.

Нужна чат-платформа, которую мы ещё не поддерживаем (Mattermost? Microsoft Teams через Power Automate?), напишите команде на /about. Тарифы и лимиты мест - на странице цен; Discord и Telegram доступны с плана Pro и выше.