Webhookovi

RolChat isporučuje događaje vašim sustavima kao potpisane HTTP POST zahtjeve. Ova stranica opisuje webhookove dodataka; webhookovi koje šalje pravilo Automatizacije razlikuju se u ponavljanjima, vremenu čekanja i rotaciji tajne, vidi Webhookovi automatizacije. Ista pravila vrijede i u suprotnom smjeru, kada vaš sustav, dodatak ili pružatelj šalje podatke u RolChat. Provjerite svaku isporuku redoslijedom navedenim u nastavku prije nego što na nju reagirate.

Kako izgleda isporuka

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

Zaglavlje	Značenje
X-RolChat-Timestamp	Unix sekunde u trenutku slanja. Dio potpisane poruke.
X-RolChat-Signature	sha256=<hex>. Prefiks navodi algoritam kako bi se kasnije mogao promijeniti.
X-RolChat-Nonce	ULID jedinstven za ovaj HTTP zahtjev. Ponavljanje dobiva novi nonce.
X-RolChat-Event-Id	Vlastiti ID događaja. Ne mijenja se pri ponavljanjima; koristite ga za deduplikaciju.

Odlazne isporuke idu samo na HTTPS krajnje točke. HTTP URL odbija se pri izradi pretplate.

Potpis

Potpisana poruka je vremenska oznaka, doslovna točka i sirovo tijelo zahtjeva, bajt po bajt:

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

Potpisujte bajtove koje ste primili, a ne ponovno serijaliziranu kopiju parsiranog JSON-a. Promjene razmaka ili redoslijeda ključeva kvare potpis. SHA-256 jedini je prihvaćeni algoritam.

Radnja automatizacije „Pošalji HTTP zahtjev”

Zahtjevi koje šalje HTTP radnja modula Automatizacija potpisuju se s dva zaglavlja. X-RolChat-Signature je sha256= plus HMAC-SHA256 samo tijela. X-RolChat-Signature-V2 je HMAC-SHA256 niza <timestamp>.<body>, tj. sheme opisane gore, s X-RolChat-Timestamp kao vremenskom oznakom. Provjeravajte zaglavlje V2; zaglavlje samo s tijelom ne štiti od ponovljenog zahtjeva. Ti zahtjevi ne nose X-RolChat-Nonce ni X-RolChat-Event-Id; svaki pokušaj jedne isporuke nosi isti X-RolChat-Delivery-Id i vlastiti broj u X-RolChat-Attempt, pa preskočite provjeru nonce vrijednosti i deduplicirajte prema X-RolChat-Delivery-Id. Primjeri provjere čitaju X-RolChat-Signature: za zahtjeve automatizacije umjesto toga čitajte X-RolChat-Signature-V2.

Provjera isporuke

Obavite ovih pet provjera redom. Primjeri u Pythonu, Node.js-u, Go-u, Rubyju i PHP-u nalaze se na stranici primjeri provjere.

1. Svježina. Odbijte ako je |now − X-RolChat-Timestamp| > 300 sekundi (400). Pet minuta tolerira odstupanje satova, a presretnuti zahtjev nakon toga postaje bezvrijedan. Držite poslužitelj sinkroniziran putem NTP-a.
2. Potpis. Izračunajte očekivanu vrijednost i usporedite je u konstantnom vremenu (hmac.compare_digest, crypto.timingSafeEqual, hash_equals). Pri nepodudaranju odbijte s 401. Obična usporedba nizova otkriva informacije kroz vrijeme izvođenja i nije prihvatljiva.
3. Nonce. Pohranite X-RolChat-Nonce s TTL-om od 10 minuta atomskim upisom ako ključ ne postoji (SET NX EX 600). Ako već postoji, odbijte s 409: zahtjev je ponovljen. Ako spremište za nonce ne radi, sigurno odbijte s 503 kako bi RolChat ponovio isporuku; nikada ne prelazite na „prihvati”.
4. Parsirajte tijelo tek sada.
5. Deduplicirajte po ID-u događaja. Ponavljanja nose novi nonce, ali isti X-RolChat-Event-Id. Ako ste taj ID obradili u posljednjih sedam dana, odgovorite s 200 bez ponovne obrade.

Odgovorite s 2xx čim je isporuka sigurno prihvaćena; posao obavite asinkrono. RolChat čeka odgovor 15 sekundi.

Tajne

• Tajna webhooka sastoji se od 64 nasumična bajta kodirana u base64url (oko 86 znakova). Generira se pri izradi pretplate ili dodatka i prikazuje se samo jednom.
• Pohranite je u vlastiti trezor ili varijablu okruženja; RolChat čuva samo šifriranu kopiju.
• Zamjena se preporučuje nakon 90 dana; proizvod prikazuje podsjetnik, ali nikada ne isključuje pretplatu zbog izostanka zamjene.
• Zamjena koristi razdoblje preklapanja: nakon POST /api/v1/plugins/{id}/webhook-secret/rotate sedam dana vrijede i stara i nova tajna, nove isporuke potpisuju se novom, a stara se briše nakon isteka razdoblja. U trenutku zamjene ništa se ne kvari.
• Ako tajna procuri, POST /api/v1/plugins/{id}/webhook-secret/revoke odmah je poništava, izdaje novu, šalje e-poštu administratorima računa i upisuje stavku u reviziju.

Ponavljanja i neisporučive poruke

Odgovor koji nije 2xx ili mrežni kvar zakazuje ponavljanje:

Pokušaj	Odgoda nakon prethodnog
1	odmah
2	15 sekundi
3	1 minuta
4	5 minuta
5	30 minuta
6	2 sata
7	8 sati
8	24 sata

408, 429, 5xx i mrežne greške se ponavljaju. 400, 401, 403, 404 i 410 ne: isporuka odmah ide u red neisporučivih poruka jer ponavljanje odbijenog potpisa ili nepostojeće krajnje točke ne može pomoći. Nakon osam neuspjelih pokušaja isporuka također odlazi u red neisporučivih poruka.

Neisporučive poruke čuvaju se 30 dana i vidljive su u Postavke → Dodaci → {plugin} → Zapisnik webhookova → DLQ, gdje ih administrator može ponovno poslati (POST /api/v1/plugins/{id}/webhook-dlq/{entry_id}/replay).

Ograničenja

• Odlazno tijelo: zadano 1 MB (prilagodljivo po dodatku). Dolazno tijelo u RolChat: 5 MB. Veće vraća 413.
• Dodatak može navesti allowed_source_ips; RolChat primjenjuje taj popis dopuštenih prije provjere.
• Kao dodatnu provjeru možete se osloniti na korisnički agent RolChat-Webhook/1.0. To nije sigurnosna kontrola.

Dolazni webhookovi u RolChat

Pružatelji šalju podatke u RolChat na /api/v1/webhooks/{category}/{adapter} koristeći vlastite sheme potpisa (Twilio, Telnyx, Bandwidth, Meta za WhatsApp, Stripe). Svaki adapter provjerava potpis svog pružatelja, normalizira sadržaj i ponovno ga objavljuje na internoj sabirnici događaja s RolChat potpisom. Vaš vlastiti sustav može slati podatke u RolChat s istim zaglavljima X-RolChat-* opisanima gore, potpisanima tajnom dodatka kojem pripada krajnja točka.

Webhookovi automatizacije

Radnja Pošalji HTTP zahtjev modula Automatizacija ima vlastita pravila isporuke:

• Jedna tajna po računu. Prikažite je ili rotirajte na zaslonu Automatizacije (Vlasnik i Administrator). Rotacija djeluje odmah: nema razdoblja preklapanja, stara tajna prestaje vrijediti istog trena, zato prvo ažurirajte primatelja ili prihvatite kratku prazninu.
• Vrijeme čekanja: RolChat čeka odgovor 10 sekundi.
• Ponavljanja: najviše 6 pokušaja ukupno. Stanka prije pokušaja 2 je 30 sekundi, zatim oko 2 minute, 8 minuta, 32 minute i 2 sata 8 minuta, svaka s odstupanjem do 20 %. Pojedina stanka nikad ne prelazi 6 sati.
• Što se ponavlja: mrežne pogreške, istek vremena, 5xx, 408, 425 i 429. Ostali odgovori 4xx, blokirana adresa ili preveliko tijelo ne ponavljaju se: isporuka ide ravno u red neisporučivih poruka, kao i nakon posljednjeg neuspjelog pokušaja.
• Zaglavlja: X-RolChat-Signature, X-RolChat-Signature-V2, X-RolChat-Timestamp, X-RolChat-Delivery-Id, X-RolChat-Attempt.

Testiranje primatelja

POST /api/v1/webhooks/test-signature šalje sintetički potpisani događaj na krajnju točku dodatka koji poziva kako biste mogli provjeriti svoju implementaciju od početka do kraja prije nego što stigne stvarni promet.

Česte pogreške

• Provjera prema parsiranom i ponovno kodiranom JSON-u umjesto prema sirovim bajtovima.
• Usporedba potpisa operatorom ==.
• Deduplikacija po nonceu (svako ponavljanje ima novi) umjesto po ID-u događaja.
• Sat koji odstupa više od pet minuta.
• Obavljanje sporog posla prije odgovora, zbog čega nastupa istek nakon 15 sekundi i isti se događaj prima ponovno.