Вебхуки

RolChat доставляє події у ваші системи у вигляді підписаних HTTP-запитів POST. Ця сторінка описує вебхуки плагінів; вебхуки, які надсилає правило Автоматизації, відрізняються повторами, часом очікування та зміною секрету, див. Вебхуки автоматизації. Ті самі правила діють і у зворотному напрямку, коли ваша система, плагін чи провайдер надсилає дані в RolChat. Перевіряйте кожну доставку в наведеному нижче порядку, перш ніж щось із нею робити.

Як виглядає доставка

POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: RolChat-Webhook/1.0
X-RolChat-Timestamp: 1713615825
X-RolChat-Signature: sha256=a1b2c3…
X-RolChat-Nonce: nonce_01HKQN9…
X-RolChat-Event-Id: evt_01HKQN9…

{ "id": "evt_01HKQN9…", "type": "conversation.created", "occurred_at": "…", "data": { … } }

Заголовок	Значення
X-RolChat-Timestamp	Unix-час надсилання в секундах. Входить до підписуваного повідомлення.
X-RolChat-Signature	sha256=<hex>. Префікс називає алгоритм, щоб його можна було змінити в майбутньому.
X-RolChat-Nonce	ULID, унікальний для цього HTTP-запиту. Повторна спроба отримує новий nonce.
X-RolChat-Event-Id	Власний ID події. Не змінюється між повторами; використовуйте його для дедуплікації.

Вихідні доставки йдуть лише на HTTPS-ендпоінти. HTTP-адресу відхиляють під час створення підписки.

Підпис

Підписуване повідомлення - це мітка часу, символ крапки та сире тіло запиту, байт у байт:

canonical = "<timestamp>.<body>"
signature = hex( HMAC-SHA256( secret, canonical ) )

Підписуйте отримані байти, а не повторно серіалізовану копію розібраного JSON. Зміни пробілів чи порядку ключів ламають підпис. SHA-256 - єдиний допустимий алгоритм.

Дія автоматизації «Send HTTP request»

Запити, які надсилає HTTP-дія модуля Автоматизація, підписуються двома заголовками. X-RolChat-Signature - це sha256= плюс HMAC-SHA256 лише від тіла. X-RolChat-Signature-V2 - це HMAC-SHA256 від <timestamp>.<body>, тобто схема, описана вище, де часова мітка береться з X-RolChat-Timestamp. Перевіряйте заголовок V2: заголовок лише від тіла не захищає від повторно надісланого запиту. Ці запити не містять X-RolChat-Nonce і X-RolChat-Event-Id; усі спроби однієї доставки мають той самий X-RolChat-Delivery-Id і власний номер у X-RolChat-Attempt, тому перевірку nonce пропустіть, а дедуплікацію робіть за X-RolChat-Delivery-Id. У прикладах перевірки читається X-RolChat-Signature: для запитів автоматизації читайте натомість X-RolChat-Signature-V2.

Перевірка доставки

Виконайте ці п’ять перевірок по черзі. Приклади на Python, Node.js, Go, Ruby і PHP наведено на сторінці прикладів перевірки.

1. Актуальність. Відхиляйте запит, якщо |now − X-RolChat-Timestamp| > 300 секунд (400). П’ять хвилин покривають розбіжність годинників і роблять перехоплений запит марним після цього часу. Синхронізуйте сервер через NTP.
2. Підпис. Обчисліть очікуване значення й порівняйте його за допомогою порівняння за сталий час (hmac.compare_digest, crypto.timingSafeEqual, hash_equals). У разі розбіжності відхиляйте з 401. Звичайне порівняння рядків розкриває інформацію через час виконання й неприпустиме.
3. Nonce. Збережіть X-RolChat-Nonce з TTL 10 хвилин атомарною операцією «записати, якщо відсутнє» (SET NX EX 600). Якщо значення вже є, відхиляйте з 409: це повтор запиту. Якщо сховище nonce недоступне, відмовляйте з 503, щоб RolChat повторив спробу; ніколи не переходьте за замовчуванням до «прийняти».
4. Розбирайте тіло лише тепер.
5. Дедуплікуйте за ID події. Повтори надходять із новим nonce, але з тим самим X-RolChat-Event-Id. Якщо цей ID уже оброблено за останні сім днів, відповідайте 200 без повторної обробки.

Відповідайте 2xx, щойно доставку надійно прийнято; саму роботу виконуйте асинхронно. RolChat чекає на відповідь 15 секунд.

Секрети

• Секрет вебхука - це 64 випадкові байти в кодуванні base64url (близько 86 символів). Його генерують під час створення підписки чи плагіна та показують один раз.
• Зберігайте його у власному сховищі секретів або в змінних середовища; RolChat зберігає лише зашифровану копію.
• Ротацію рекомендовано через 90 днів; продукт показує нагадування, але ніколи не вимикає підписку через відсутність ротації.
• Ротація використовує вікно перекриття: після POST /api/v1/plugins/{id}/webhook-secret/rotate і старий, і новий секрет проходять перевірку протягом семи днів, нові доставки підписуються новим секретом, а старий видаляється після завершення вікна. У момент ротації нічого не ламається.
• Якщо секрет витік, POST /api/v1/plugins/{id}/webhook-secret/revoke негайно робить його недійсним, випускає новий, надсилає лист адміністраторам акаунта й створює запис у журналі аудиту.

Повтори та недоставлені повідомлення

Відповідь не з діапазону 2xx або мережевий збій планує повторну спробу:

Спроба	Затримка після попередньої
1	одразу
2	15 секунд
3	1 хвилина
4	5 хвилин
5	30 хвилин
6	2 години
7	8 годин
8	24 години

408, 429, 5xx і мережеві помилки повторюються. 400, 401, 403, 404 і 410 не повторюються: доставка одразу потрапляє до черги недоставлених повідомлень, бо повтор відхиленого підпису чи відсутнього ендпоінта не допоможе. Після восьми невдалих спроб доставка також потрапляє до цієї черги.

Недоставлені повідомлення зберігаються 30 днів і видні в розділі Налаштування → Плагіни → {плагін} → Журнал вебхуків → DLQ, де адміністратор може повторно надіслати будь-яке з них (POST /api/v1/plugins/{id}/webhook-dlq/{entry_id}/replay).

Ліміти

• Вихідне тіло: за замовчуванням 1 MB (налаштовується для кожного плагіна). Вхідне тіло в RolChat: 5 MB. Більше - 413.
• Плагін може оголосити allowed_source_ips; RolChat застосовує цей список дозволених адрес до перевірки підпису.
• Як додаткову перевірку можна орієнтуватися на user agent RolChat-Webhook/1.0. Це не засіб захисту.

Вхідні вебхуки в RolChat

Провайдери надсилають дані в RolChat на /api/v1/webhooks/{category}/{adapter}, використовуючи власні схеми підпису (Twilio, Telnyx, Bandwidth, Meta для WhatsApp, Stripe). Кожен адаптер перевіряє підпис свого провайдера, нормалізує дані й повторно публікує їх у внутрішній шині подій із підписом RolChat. Ваша власна система може надсилати дані в RolChat із тими самими заголовками X-RolChat-*, описаними вище, підписаними секретом плагіна, якому належить ендпоінт.

Вебхуки автоматизації

Дія Надіслати HTTP-запит модуля «Автоматизація» має власні правила доставки:

• Один секрет на акаунт. Показати чи змінити його можна на екрані «Автоматизація» (Власник і Адміністратор). Зміна діє одразу: вікна перекриття немає, старий секрет перестає проходити перевірку негайно, тож спершу оновіть приймач або змиріться з короткою перервою.
• Час очікування: RolChat чекає на відповідь 10 секунд.
• Повтори: разом до 6 спроб. Пауза перед 2-ю спробою - 30 секунд, далі приблизно 2 хвилини, 8 хвилин, 32 хвилини та 2 години 8 хвилин, кожна зі зсувом до 20 %. Жодна пауза не перевищує 6 годин.
• Що повторюється: мережеві помилки, тайм-аути, 5xx, 408, 425 і 429. Інші відповіді 4xx, заблокована адреса чи завеликий вміст не повторюються: доставка одразу потрапляє до черги недоставлених повідомлень, як і після останньої невдалої спроби.
• Заголовки: X-RolChat-Signature, X-RolChat-Signature-V2, X-RolChat-Timestamp, X-RolChat-Delivery-Id, X-RolChat-Attempt.

Тестування приймача

POST /api/v1/webhooks/test-signature надсилає синтетичну підписану подію на ендпоінт плагіна, що викликає, щоб ви могли перевірити свою реалізацію від початку до кінця до появи реального трафіку.

Типові помилки

• Перевірка за розібраним і заново закодованим JSON замість сирих байтів.
• Використання == для порівняння підписів.
• Дедуплікація за nonce (у кожного повтору він новий) замість ID події.
• Годинник, що відстає чи поспішає більш ніж на п’ять хвилин.
• Повільна робота до відповіді, через яку спрацьовує тайм-аут 15 секунд і та сама подія надходить знову.