Вебхуки — события модерации в реальном времени в ваших системах

1Что делают вебхуки

Вместо опроса API вы регистрируете URL, и Telm отправляет на него подписанный HTTP POST всякий раз, когда что-то происходит в вашей группе. Именно так вы получаете события модерации в свои собственные системы — дашборд, хранилище данных, канал оповещений — в реальном времени.

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

2Почему пуш лучше опроса

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

Типичные применения включают зеркалирование банов в ваши собственные админ-инструменты, оповещение командного канала при обнаружении рейда, трансляцию обнаружений в аналитику или запуск рабочего процесса, когда участник вступает или уходит.

• В реальном времени: вы узнаёте о событии, когда оно происходит, а не при следующем опросе.
• Эффективно: никаких повторных чтений, которые съедают вашу дневную квоту.
• Полно: доставки повторяются, так что краткий простой на вашей стороне не теряет события.

3События, на которые можно подписаться

Есть семь типов событий, на которые можно подписаться, охватывающих вердикты спама, наказания и изменения членства. Одно модерируемое сообщение может произвести более одного события — спам-сообщение, которое заканчивается баном, испускает и spam.detected, и user.banned.

• spam.detected — движок пометил сообщение как спам.
• message.suspicious — теневое (режим наблюдения) обнаружение с оценкой.
• user.banned — участник был забанен.
• user.kicked — участник был удалён.
• user.muted — участник был замьючен.
• user.joined — участник вступил в группу.
• user.left — участник покинул группу.

4Конверт полезной нагрузки

Каждая доставка — это JSON-конверт с небольшим, стабильным набором полей верхнего уровня и специфичным для события объектом data внутри. Вы можете маршрутизировать по типу и времени, не разбирая детали, пока они вам не понадобятся.

• id — уникальный delivery id; повторные доставки одного события переиспользуют тот же id, чем вы и дедуплицируете.
• type — тип события, один из семи выше.
• created_at — когда событие сработало, в RFC3339 UTC.
• group_id — группа, к которой относится событие (когда применимо).
• data — специфичный для события объект: детали сообщения и вердикта для событий спама, детали участника для событий членства.

5Проверка того, что доставки действительно от Telm

Каждая доставка подписана, так что ваш сервер может подтвердить, что запрос действительно пришёл от Telm и не был подделан в пути. Проверяйте подпись до того, как доверять полезной нагрузке, и отклоняйте всё, что не совпадает.

Подпись — это HMAC-SHA256 от метки времени и сырого тела запроса, с ключом — вашим секретом подписи эндпоинта. Чтобы проверить, пересчитайте HMAC над заголовком метки времени и точными байтами, которые вы получили, и сравните его с заголовком подписи.

• X-Telm-Signature — подпись, в формате v1, за которым следует hex HMAC-SHA256 от метки времени, соединённой с телом.
• X-Telm-Timestamp — метка времени в unix-секундах, которая подписана, так что вы можете отклонять устаревшие или переигранные доставки.
• X-Telm-Event — тип события, а X-Telm-Delivery — delivery id для дедупликации.
• Секрет подписи показывается один раз при создании эндпоинта и начинается с whsec_. Храните его надёжно; это единственное, что доказывает подлинность доставки.

6Надёжная, дедуплицированная доставка

Доставка «хотя бы один раз»: Telm обеспечивает, что событие достигнет вас, а значит, одно и то же событие может изредка прийти дважды. Поскольку каждая повторная доставка переиспользует тот же delivery id, вы дедуплицируете, храня id, которые обработали, и пропуская повторы.

Если ваш эндпоинт недоступен или возвращает ошибку, доставка повторяется по фиксированному расписанию — примерно через минуту, пять минут, тридцать минут, два часа и шесть часов, до шести попыток за примерно восемь с половиной часов. Эндпоинт, который продолжает падать, автоматически отключается, чтобы защитить обе стороны, и владелец уведомляется.

• Отвечайте быстро статусом 2xx; тяжёлую работу делайте асинхронно после подтверждения.
• Дедуплицируйте по delivery id — никогда по содержимому полезной нагрузки.
• Эндпоинт, который падает около двадцати раз подряд без успеха в течение 72-часового окна, автоматически отключается; включите его снова, как только ваш сервер здоров.

7Управление эндпоинтами и чтение лога

Вы регистрируете, редактируете и удаляете эндпоинты вебхуков через API. Когда вы создаёте один, вы получаете секрет подписи ровно один раз, выбираете события для подписки и при желании ограничиваете его конкретными группами. Тестовый вызов отправляет подписанный пинг, так что вы можете подтвердить, что ваша проверка работает, до того как начнётся реальный трафик.

Каждый эндпоинт держит лог доставок, который вы можете перечитать, чтобы увидеть, что было отправлено, когда и успешно ли — удобно для отладки приёмника, не дожидаясь следующего живого события.

• Создайте эндпоинт и скопируйте секрет whsec_ немедленно.
• Отправьте тестовый пинг, чтобы проверить свою проверку подписи от начала до конца.
• Ограничьте эндпоинт одной группой или оставьте его открытым для всех групп, которыми вы администрируете.
• Читайте лог доставок, чтобы изучить недавние попытки и их результаты.

8Лучшие практики и частые ошибки

Надёжный приёмник следует нескольким правилам, которые предотвращают самые частые проблемы.

• Проверяйте подпись над сырыми байтами тела — разбор в JSON сначала и повторная сериализация могут изменить байты и сломать проверку.
• Возвращайте 2xx быстро и обрабатывайте позже; медленный обработчик вызывает таймауты и ненужные повторы.
• Делайте обработку идемпотентной, чтобы повторно доставленное событие не считалось дважды.
• Используйте HTTPS на публично доступном URL; Telm блокирует внутренние и приватные адреса и не следует за редиректами.
• Держите секрет whsec_ вне логов и клиентского кода.