Уебхукове

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 е единственият приет алгоритъм.

Заявките, изпратени от 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 има на страницата с примери за проверка.

Актуалност. Отхвърлете, ако |now − X-RolChat-Timestamp| > 300 секунди (400). Пет минути покриват разминаването на часовниците и правят прихванатата заявка безполезна след това. Поддържайте сървъра си синхронизиран с NTP.
Подпис. Изчислете очакваната стойност и сравнете със сравнение с постоянно време (hmac.compare_digest, crypto.timingSafeEqual, hash_equals). При несъответствие отхвърлете с 401. Обикновено сравнение на низове издава информация чрез времето за изпълнение и не е приемливо.
Nonce. Запазете X-RolChat-Nonce с TTL 10 минути чрез атомарна операция „запиши, ако липсва“ (SET NX EX 600). Ако вече съществува, отхвърлете с 409: заявката е повторение. Ако хранилището за nonce не работи, откажете с 503, за да опита RolChat отново; никога не преминавайте към „приеми“ по подразбиране.
Анализирайте тялото едва сега.
Премахнете дубликатите по 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 заявка на модула «Автоматизация» има собствени правила за доставка:

Една тайна на акаунт. Показвате или сменяте я на екрана «Автоматизация» (Owner и Admin). Смяната влиза в сила веднага: няма период на препокриване, старата тайна спира да се проверява незабавно, затова първо обновете приемника си или приемете кратка пауза.
Време за изчакване: 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 секунди и същото събитие пристига отново.