Webhooky

RolChat doručuje udalosti do vašich systémov ako podpísané požiadavky HTTP POST. Táto stránka opisuje webhooky pluginov; webhooky odosielané pravidlom Automatizácie sa líšia opakovaniami, časom čakania a výmenou tajomstva, pozri Webhooky automatizácie. Rovnaké pravidlá platia aj opačným smerom, keď váš systém, plugin alebo poskytovateľ posiela dáta do RolChat. Každé doručenie overte v poradí uvedenom nižšie, skôr než naň zareagujete.

Ako doručenie vyzerá

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": { … } }

Hlavička	Význam
X-RolChat-Timestamp	Unixové sekundy v okamihu odoslania. Súčasť podpisovanej správy.
X-RolChat-Signature	sha256=<hex>. Prefix určuje algoritmus, aby ho bolo možné neskôr zmeniť.
X-RolChat-Nonce	ULID jedinečný pre túto požiadavku HTTP. Opakovanie dostane nový nonce.
X-RolChat-Event-Id	Vlastné ID udalosti. Pri opakovaniach sa nemení; používajte ho na deduplikáciu.

Odchádzajúce doručenia smerujú len na endpointy HTTPS. URL s HTTP sa odmietne už pri vytváraní odberu.

Podpis

Podpisovaná správa je časová pečiatka, doslovná bodka a surové telo požiadavky, bajt po bajte:

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

Podpisujte bajty, ktoré ste prijali, nie znova serializovanú kópiu naparsovaného JSON. Zmeny bielych znakov alebo poradia kľúčov podpis pokazia. SHA-256 je jediný prijímaný algoritmus.

Akcia automatizácie „Odoslať HTTP požiadavku“

Požiadavky odoslané HTTP akciou modulu Automatizácia sú podpísané dvoma hlavičkami. X-RolChat-Signature je sha256= plus HMAC-SHA256 iba z tela. X-RolChat-Signature-V2 je HMAC-SHA256 z <timestamp>.<body>, teda schéma opísaná vyššie, pričom časovou pečiatkou je X-RolChat-Timestamp. Overujte hlavičku V2; hlavička iba s telom nechráni pred opakovaným prehraním požiadavky. Tieto požiadavky nenesú X-RolChat-Nonce ani X-RolChat-Event-Id; všetky pokusy jedného doručenia nesú rovnaké X-RolChat-Delivery-Id a vlastné číslo v X-RolChat-Attempt, preto vynechajte kontrolu nonce a deduplikujte podľa X-RolChat-Delivery-Id. Ukážky overenia čítajú X-RolChat-Signature: pri požiadavkách automatizácie čítajte namiesto toho X-RolChat-Signature-V2.

Overenie doručenia

Vykonajte týchto päť kontrol v tomto poradí. Ukážky v Pythone, Node.js, Go, Ruby a PHP nájdete na stránke ukážok overenia.

1. Čerstvosť. Odmietnite, ak |now − X-RolChat-Timestamp| > 300 sekúnd (400). Päť minút toleruje rozdiel hodín a zachytená požiadavka je potom na nič. Synchronizujte server cez NTP.
2. Podpis. Vypočítajte očakávanú hodnotu a porovnajte ju v konštantnom čase (hmac.compare_digest, crypto.timingSafeEqual, hash_equals). Pri nezhode odmietnite s 401. Bežné porovnanie reťazcov prezrádza informácie časovaním a nie je prijateľné.
3. Nonce. Uložte X-RolChat-Nonce s TTL 10 minút pomocou atomického zápisu, ak kľúč neexistuje (SET NX EX 600). Ak už existuje, odmietnite s 409: ide o opakované prehranie. Ak úložisko nonce nefunguje, bezpečne zlyhajte s 503, aby RolChat doručenie zopakoval; nikdy neprechádzajte na „prijať“.
4. Parsujte telo až teraz.
5. Deduplikujte podľa ID udalosti. Opakovania nesú nový nonce, ale rovnaké X-RolChat-Event-Id. Ak ste toto ID spracovali počas posledných siedmich dní, odpovedzte 200 bez opätovného spracovania.

Odpovedzte 2xx, len čo je doručenie bezpečne prijaté; prácu vykonajte asynchrónne. RolChat čaká na odpoveď 15 sekúnd.

Tajné kľúče

• Tajný kľúč webhooku je 64 náhodných bajtov kódovaných v base64url (asi 86 znakov). Vygeneruje sa pri vytvorení odberu alebo pluginu a zobrazí sa iba raz.
• Uložte ho do vlastného trezoru alebo premennej prostredia; RolChat uchováva len šifrovanú kópiu.
• Výmena sa odporúča po 90 dňoch; produkt zobrazí pripomienku, ale odber kvôli chýbajúcej výmene nikdy nevypne.
• Výmena využíva prekryvné obdobie: po POST /api/v1/plugins/{id}/webhook-secret/rotate sa sedem dní overuje starý aj nový kľúč, nové doručenia sa podpisujú novým a starý sa po uplynutí obdobia zmaže. V okamihu výmeny sa nič nepokazí.
• Ak tajný kľúč unikne, POST /api/v1/plugins/{id}/webhook-secret/revoke ho okamžite zneplatní, vydá nový, pošle e-mail administrátorom účtu a zapíše položku do auditu.

Opakovania a nedoručiteľné správy

Odpoveď iná než 2xx alebo sieťové zlyhanie naplánuje opakovanie:

Pokus	Oneskorenie po predchádzajúcom
1	okamžite
2	15 sekúnd
3	1 minúta
4	5 minút
5	30 minút
6	2 hodiny
7	8 hodín
8	24 hodín

408, 429, 5xx a sieťové chyby sa opakujú. 400, 401, 403, 404 a 410 nie: doručenie ide rovno do frontu nedoručiteľných správ, pretože opakovanie odmietnutého podpisu alebo chýbajúceho endpointu nemôže pomôcť. Po ôsmich neúspešných pokusoch ide do frontu nedoručiteľných správ tiež.

Nedoručiteľné správy sa uchovávajú 30 dní a sú viditeľné v Nastavenia → Pluginy → {plugin} → Log webhookov → DLQ, kde ich administrátor môže znova odoslať (POST /api/v1/plugins/{id}/webhook-dlq/{entry_id}/replay).

Limity

• Odchádzajúce telo: predvolene 1 MB (nastaviteľné pre každý plugin). Prichádzajúce telo do RolChat: 5 MB. Väčšie vracia 413.
• Plugin môže deklarovať allowed_source_ips; RolChat tento zoznam povolených uplatní pred overením.
• Ako doplnkovú kontrolu môžete overovať user agent RolChat-Webhook/1.0. Nejde o bezpečnostný mechanizmus.

Prichádzajúce webhooky do RolChat

Poskytovatelia posielajú dáta do RolChat na /api/v1/webhooks/{category}/{adapter} s vlastnými schémami podpisov (Twilio, Telnyx, Bandwidth, Meta pre WhatsApp, Stripe). Každý adaptér overí podpis svojho poskytovateľa, normalizuje obsah a znova ho publikuje na internej zbernici udalostí s podpisom RolChat. Váš vlastný systém môže posielať dáta do RolChat s rovnakými hlavičkami X-RolChat-* opísanými vyššie, podpísané tajným kľúčom pluginu, ktorému endpoint patrí.

Webhooky automatizácie

Akcia Odoslať požiadavku HTTP modulu Automatizácia má vlastné pravidlá doručovania:

• Jedno tajomstvo na účet. Zobraziť ho alebo vymeniť môžete na obrazovke Automatizácie (Vlastník a Administrátor). Výmena platí okamžite: neexistuje okno prekrytia, staré tajomstvo prestane overovať hneď, preto najprv aktualizujte príjemcu alebo rátajte s krátkou odstávkou.
• Čas čakania: RolChat čaká na odpoveď 10 sekúnd.
• Opakovania: celkovo najviac 6 pokusov. Pauza pred 2. pokusom je 30 sekúnd, potom približne 2 minúty, 8 minút, 32 minút a 2 hodiny 8 minút, každá s odchýlkou do 20 %. Jedna pauza nikdy nepresiahne 6 hodín.
• Čo sa opakuje: chyby siete, časové limity, 5xx, 408, 425 a 429. Iné odpovede 4xx, blokovaná adresa alebo príliš veľké telo sa neopakujú: doručenie ide rovno do fronty nedoručiteľných správ, rovnako ako po poslednom neúspešnom pokuse.
• Hlavičky: X-RolChat-Signature, X-RolChat-Signature-V2, X-RolChat-Timestamp, X-RolChat-Delivery-Id, X-RolChat-Attempt.

Testovanie príjemcu

POST /api/v1/webhooks/test-signature pošle syntetickú podpísanú udalosť na endpoint volajúceho pluginu, aby ste mohli implementáciu overiť od začiatku do konca skôr, než príde skutočná prevádzka.

Časté chyby

• Overovanie voči naparsovanému a znova zakódovanému JSON namiesto surových bajtov.
• Porovnávanie podpisov pomocou ==.
• Deduplikácia podľa nonce (každé opakovanie má nový) namiesto podľa ID udalosti.
• Hodiny posunuté o viac než päť minút.
• Pomalá práca pred odpoveďou, následné vypršanie 15 sekúnd a opätovné prijatie tej istej udalosti.