Вебхуки — події модерації в реальному часі у ваших системах

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 всередині. Ви можете маршрутизувати за type і часом, не розбираючи деталей, доки вони не знадобляться.

• id — унікальний 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 — id доставки для дедуплікації.
• Секрет підпису показується один раз під час створення ендпоінта й починається з whsec_. Зберігайте його безпечно; це єдине, що доводить справжність доставки.

6Надійна доставка з дедуплікацією

Доставка щонайменше одноразова: Telm дбає, щоб подія дійшла до вас, а це означає, що та сама подія іноді може надійти двічі. Оскільки кожна повторна доставка повторно використовує той самий id доставки, ви дедуплікуєте, зберігаючи оброблені id й пропускаючи повтори.

Якщо ваш ендпоінт недосяжний чи повертає помилку, доставка повторюється за фіксованим розкладом — приблизно за хвилину, п'ять хвилин, тридцять хвилин, дві години й шість годин, до шести спроб протягом приблизно восьми з половиною годин. Ендпоінт, що весь час зазнає невдач, автоматично вимикається, щоб захистити обидві сторони, а власника сповіщають.

• Відповідайте швидко статусом 2xx; важку роботу виконуйте асинхронно після підтвердження.
• Дедуплікуйте за id доставки — ніколи за вмістом корисного навантаження.
• Ендпоінт, що зазнає невдачі близько двадцяти разів поспіль без жодного успіху в межах 72-годинного вікна, автоматично вимикається; знову ввімкніть його, щойно ваш сервер буде здоровим.

7Керування ендпоінтами та читання журналу

Ви реєструєте, редагуєте й видаляєте ендпоінти вебхуків через API. Коли ви створюєте один, ви отримуєте секрет підпису рівно один раз, обираєте події для підписки й за бажанням обмежуєте його конкретними групами. Тестовий виклик надсилає підписаний пінг, тож ви можете підтвердити, що ваша перевірка працює, перш ніж почнеться реальний трафік.

Кожен ендпоінт зберігає журнал доставок, який ви можете прочитати, щоб побачити, що було надіслано, коли й чи вдалося — зручно для налагодження приймача, не чекаючи на наступну живу подію.

• Створіть ендпоінт і скопіюйте секрет whsec_ одразу.
• Надішліть тестовий пінг, щоб валідувати вашу перевірку підпису від початку до кінця.
• Обмежте ендпоінт однією групою чи лишіть його відкритим для всіх груп, які ви адмініструєте.
• Читайте журнал доставок, щоб оглянути нещодавні спроби та їхні результати.

8Найкращі практики та поширені помилки

Надійний приймач дотримується кількох правил, що запобігають найпоширенішим проблемам.

• Перевіряйте підпис над сирими байтами тіла — розбір у JSON першим і повторна серіалізація можуть змінити байти й зламати перевірку.
• Повертайте 2xx швидко й обробляйте пізніше; повільний обробник спричиняє тайм-аути й зайві повтори.
• Робіть обробку ідемпотентною, щоб повторно доставлена подія не рахувалася двічі.
• Використовуйте HTTPS на публічно досяжній URL-адресі; Telm блокує внутрішні й приватні адреси й не переходить за редиректами.
• Тримайте секрет whsec_ поза журналами й клієнтським кодом.