Вебхукови

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 URL се одбива при креирањето на претплатата.

Потписот

Потпишаната порака е временската ознака, буквална точка и суровото тело на барањето, бајт по бајт:

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 дена и се видливи во Поставки → Плагини → {plugin} → Дневник на вебхукови → DLQ, каде што администраторот може повторно да испрати една (POST /api/v1/plugins/{id}/webhook-dlq/{entry_id}/replay).

Ограничувања

Одлезно тело: стандардно 1 MB (може да се конфигурира по плагин). Дојдовно тело во RolChat: 5 MB. Поголемото враќа 413.
Плагинот може да декларира allowed_source_ips; RolChat ја применува таа листа на дозволени адреси пред проверката.
Можете да го проверувате корисничкиот агент 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 секунди и повторно примање на истиот настан.