Telm может пушить события модерации на ваш сервер в реальном времени. Вы регистрируете эндпоинт, выбираете, какие события получать, и Telm отправляет подписанный POST на каждое из них. Каждая доставка несёт подпись HMAC-SHA256, которую вы проверяете секретом эндпоинта. Неудавшиеся доставки повторяются по расписанию; постоянно недоступный эндпоинт автоматически отключается.
1Конверт события
Каждый вебхук — это HTTP POST с телом JSON в общем конверте. У конверта есть id (уникальный идентификатор доставки для дедупликации), type (имя события), метка времени created_at, group_id, к которому относится событие, и объект data, форма которого зависит от типа события.
id детерминирован для реальных событий, поэтому если то же событие доставлено дважды — например, после повтора — вы получаете один и тот же id оба раза. Используйте заголовок X-Telm-Delivery (который зеркалит этот id) как ключ идемпотентности, чтобы ваш обработчик обрабатывал каждое событие только один раз.
- Поля конверта: id, type, created_at, group_id, data.
- type — одно из имён событий из каталога ниже.
- data несёт поля, специфичные для события.
- Используйте id (и заголовок X-Telm-Delivery) для дедупликации повторов.
2Каталог событий
Вы подписываете эндпоинт на любое подмножество каталога. spam.detected срабатывает, когда движок помечает сообщение как спам. message.suspicious срабатывает в режиме наблюдения, когда движок подействовал бы, но лишь теневым образом оценил сообщение. События участников охватывают вход, выход и наказание людей.
Событие ping особенное: оно не является частью подписываемого каталога и отправляется только когда вы запускаете тестовую доставку для эндпоинта, чтобы вы могли убедиться, что ваш приёмник и проверка подписи работают из конца в конец.
- spam.detected — сообщение классифицировано как спам.
- message.suspicious — теневое обнаружение (в режиме наблюдения).
- user.banned, user.kicked, user.muted — применено действие модерации.
- user.joined, user.left — участник вошёл в группу или покинул её.
- ping — ручное тестовое событие, никогда не срабатывает от реальной активности.
3Поля полезной нагрузки по событиям
Для spam.detected и message.suspicious объект data несёт message_id, user_id, username, текст сообщения (усечённый для очень длинных сообщений), предпринятое действие, категорию, причину, обнаруженный язык и оценку уверенности. message.suspicious дополнительно несёт теневую оценку.
Для событий участников (user.joined, user.left, user.banned, user.kicked, user.muted) объект data несёт user_id, username, first_name, опциональный message_id и причину там, где она применима. Одно базовое событие может произвести более одного вебхука — спам-сообщение, вызывающее бан, доставляется и как spam.detected, и как user.banned.
- События спама: message_id, user_id, username, text, action, category, reason, language, confidence (плюс score для message.suspicious).
- События участников: user_id, username, first_name, message_id, reason.
- Один инцидент может выпустить несколько событий; сопоставляйте их по user_id и group_id.
4Проверка подписи HMAC
Каждая доставка подписывается, чтобы вы могли быть уверены, что она действительно пришла от Telm и не была подделана. Вы получаете секрет эндпоинта (он начинается с whsec_) один раз, когда создаёте эндпоинт. Сохраните его и используйте для проверки каждого входящего запроса.
Чтобы проверить, возьмите значение заголовка X-Telm-Timestamp, добавьте точку, затем добавьте точное сырое тело запроса и вычислите HMAC-SHA256 этой строки, используя секрет эндпоинта как ключ. Закодируйте результат в hex и добавьте префикс v1= — он должен равняться заголовку X-Telm-Signature. Сравнивайте константным по времени сравнением и отклоняйте запрос, если метка времени старше нескольких минут (пять — хороший порог), чтобы блокировать повторные атаки.
- X-Telm-Event — тип события.
- X-Telm-Delivery — id доставки (ключ идемпотентности).
- X-Telm-Timestamp — unix-секунды, подписаны для предотвращения повторов.
- X-Telm-Signature — v1= плюс hex HMAC-SHA256 от метки времени, точки и сырого тела.
5Доставка, повторы и автоотключение
Доставка считается успешной, только если ваш эндпоинт отвечает статусом 2xx. Всё остальное — код не из 2xx, таймаут или ошибка соединения — трактуется как неудача и повторяется по фиксированному расписанию: немедленно, затем через 1 минуту, 5 минут, 30 минут, 2 часа и 6 часов, за шесть попыток, охватывающих примерно восемь с половиной часов, прежде чем доставка закрывается как неудавшаяся.
Если эндпоинт продолжает падать — минимум двадцать неудач подряд без единой успешной доставки в течение трёх дней — Telm автоматически отключает его, чтобы он перестал слать на мёртвый URL. Вы можете снова включить его из дашборда, когда ваш приёмник снова здоров.
- Успех = HTTP 2xx. Отвечайте быстро (примерно за десять секунд) и делайте тяжёлую работу асинхронно.
- Расписание повторов: немедленно, +1м, +5м, +30м, +2ч, +6ч (шесть попыток).
- Автоотключение после 20 неудач подряд без успеха за 72 часа.
- Регистрация вебхуков требует тарифа Pro или выше.