Webhooky

RolChat doručuje události do vašich systémů jako podepsané požadavky HTTP POST. Tato stránka popisuje webhooky pluginů; webhooky odesílané pravidlem Automatizace se liší opakováním, dobou čekání a rotací tajného klíče, viz Webhooky automatizace. Stejná pravidla platí i opačným směrem, když váš systém, plugin nebo poskytovatel posílá data do RolChat. Každé doručení ověřte v pořadí uvedeném níže, než na něj zareagujete.

Jak doručení vypadá

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 okamžiku odeslání. Součást podepisované zprávy.
X-RolChat-Signature	sha256=<hex>. Prefix určuje algoritmus, aby ho bylo možné později změnit.
X-RolChat-Nonce	ULID jedinečný pro tento požadavek HTTP. Opakování dostane nový nonce.
X-RolChat-Event-Id	Vlastní ID události. Při opakováních se nemění; používejte ho k deduplikaci.

Odchozí doručení míří jen na endpointy HTTPS. URL s HTTP se odmítne už při vytváření odběru.

Podpis

Podepisovaná zpráva je časové razítko, doslovná tečka a surové tělo požadavku, bajt po bajtu:

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

Podepisujte bajty, které jste přijali, ne znovu serializovanou kopii naparsovaného JSON. Změny bílých znaků nebo pořadí klíčů podpis rozbijí. SHA-256 je jediný přijímaný algoritmus.

Akce automatizace „Odeslat HTTP požadavek“

Požadavky odeslané HTTP akcí modulu Automatizace jsou podepsány dvěma hlavičkami. X-RolChat-Signature je sha256= plus HMAC-SHA256 pouze z těla. X-RolChat-Signature-V2 je HMAC-SHA256 z <timestamp>.<body>, tedy schéma popsané výše, přičemž časovým razítkem je X-RolChat-Timestamp. Ověřujte hlavičku V2; hlavička pouze z těla nechrání před opakovaným přehráním požadavku. Tyto požadavky nenesou X-RolChat-Nonce ani X-RolChat-Event-Id; každý pokus jednoho doručení nese stejné X-RolChat-Delivery-Id a vlastní číslo v X-RolChat-Attempt, proto kontrolu nonce přeskočte a deduplikujte podle X-RolChat-Delivery-Id. Ukázky ověření čtou X-RolChat-Signature: u požadavků z automatizace čtěte místo ní X-RolChat-Signature-V2.

Ověření doručení

Proveďte těchto pět kontrol v tomto pořadí. Ukázky v Pythonu, Node.js, Go, Ruby a PHP najdete na stránce ukázek ověření.

1. Čerstvost. Odmítněte, pokud |now − X-RolChat-Timestamp| > 300 sekund (400). Pět minut toleruje rozdíl hodin a zachycený požadavek je potom k ničemu. Synchronizujte server přes NTP.
2. Podpis. Vypočítejte očekávanou hodnotu a porovnejte ji v konstantním čase (hmac.compare_digest, crypto.timingSafeEqual, hash_equals). Při neshodě odmítněte s 401. Běžné porovnání řetězců prozrazuje informace časováním a není přijatelné.
3. Nonce. Uložte X-RolChat-Nonce s TTL 10 minut pomocí atomického zápisu, pokud klíč neexistuje (SET NX EX 600). Pokud už existuje, odmítněte s 409: jde o opakované přehrání. Pokud úložiště nonce nefunguje, bezpečně selžte s 503, aby RolChat doručení zopakoval; nikdy nepřecházejte na „přijmout“.
4. Parsujte tělo až teď.
5. Deduplikujte podle ID události. Opakování nesou nový nonce, ale stejné X-RolChat-Event-Id. Pokud jste toto ID zpracovali během posledních sedmi dnů, odpovězte 200 bez opětovného zpracování.

Odpovězte 2xx, jakmile je doručení bezpečně přijato; práci proveďte asynchronně. RolChat čeká na odpověď 15 sekund.

Tajné klíče

• Tajný klíč webhooku je 64 náhodných bajtů kódovaných v base64url (asi 86 znaků). Vygeneruje se při vytvoření odběru nebo pluginu a zobrazí se jen jednou.
• Uložte ho do vlastního trezoru nebo proměnné prostředí; RolChat uchovává jen šifrovanou kopii.
• Výměna se doporučuje po 90 dnech; produkt zobrazí připomínku, ale odběr kvůli chybějící výměně nikdy nevypne.
• Výměna využívá překryvné období: po POST /api/v1/plugins/{id}/webhook-secret/rotate se sedm dní ověřuje starý i nový klíč, nová doručení se podepisují novým a starý se po uplynutí období smaže. V okamžiku výměny se nic nerozbije.
• Pokud tajný klíč unikne, POST /api/v1/plugins/{id}/webhook-secret/revoke ho okamžitě zneplatní, vydá nový, pošle e-mail administrátorům účtu a zapíše položku do auditu.

Opakování a nedoručitelné zprávy

Odpověď jiná než 2xx nebo síťové selhání naplánuje opakování:

Pokus	Prodleva po předchozím
1	okamžitě
2	15 sekund
3	1 minuta
4	5 minut
5	30 minut
6	2 hodiny
7	8 hodin
8	24 hodin

408, 429, 5xx a síťové chyby se opakují. 400, 401, 403, 404 a 410 ne: doručení jde rovnou do fronty nedoručitelných zpráv, protože opakování odmítnutého podpisu nebo chybějícího endpointu nemůže pomoci. Po osmi neúspěšných pokusech jde do fronty nedoručitelných zpráv také.

Nedoručitelné zprávy se uchovávají 30 dní a jsou vidět v Nastavení → Pluginy → {plugin} → Log webhooků → DLQ, kde je administrátor může znovu odeslat (POST /api/v1/plugins/{id}/webhook-dlq/{entry_id}/replay).

Limity

• Odchozí tělo: ve výchozím stavu 1 MB (nastavitelné pro každý plugin). Příchozí tělo do RolChat: 5 MB. Větší vrací 413.
• Plugin může deklarovat allowed_source_ips; RolChat tento seznam povolených uplatní před ověřením.
• Jako doplňkovou kontrolu můžete ověřovat user agent RolChat-Webhook/1.0. Nejde o bezpečnostní mechanismus.

Příchozí webhooky do RolChat

Poskytovatelé posílají data do RolChat na /api/v1/webhooks/{category}/{adapter} s vlastními schématy podpisů (Twilio, Telnyx, Bandwidth, Meta pro WhatsApp, Stripe). Každý adaptér ověří podpis svého poskytovatele, normalizuje obsah a znovu ho publikuje na interní sběrnici událostí s podpisem RolChat. Váš vlastní systém může posílat data do RolChat se stejnými hlavičkami X-RolChat-* popsanými výše, podepsané tajným klíčem pluginu, kterému endpoint patří.

Webhooky automatizace

Akce Odeslat HTTP požadavek modulu Automatizace má vlastní pravidla doručování:

• Jeden tajný klíč na účet. Zobrazte ho nebo otočte na obrazovce Automatizace (Vlastník a Administrátor). Rotace se projeví okamžitě: neexistuje překryvné okno, starý klíč přestane ověřovat ihned, proto nejprve aktualizujte příjemce nebo počítejte s krátkou mezerou.
• Doba čekání: RolChat čeká na odpověď 10 sekund.
• Opakování: nejvýše 6 pokusů celkem. Pauza před pokusem 2 je 30 sekund, poté přibližně 2 minuty, 8 minut, 32 minut a 2 hodiny 8 minut, každá s odchylkou až 20 %. Jedna pauza nikdy nepřesáhne 6 hodin.
• Co se opakuje: chyby sítě, vypršení času, 5xx, 408, 425 a 429. Jiné odpovědi 4xx, zablokovaná adresa nebo příliš velké tělo se neopakují: doručení jde rovnou do fronty nedoručitelných zpráv, stejně jako po posledním neúspěšném pokusu.
• Hlavičky: X-RolChat-Signature, X-RolChat-Signature-V2, X-RolChat-Timestamp, X-RolChat-Delivery-Id, X-RolChat-Attempt.

Testování příjemce

POST /api/v1/webhooks/test-signature pošle syntetickou podepsanou událost na endpoint volajícího pluginu, abyste mohli implementaci ověřit od začátku do konce dřív, než přijde skutečný provoz.

Časté chyby

• Ověřování vůči naparsovanému a znovu zakódovanému JSON místo surových bajtů.
• Porovnávání podpisů pomocí ==.
• Deduplikace podle nonce (každé opakování má nový) místo podle ID události.
• Hodiny posunuté o víc než pět minut.
• Pomalá práce před odpovědí, následné vypršení 15 sekund a opětovné přijetí stejné události.