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 чи вище.