Webhooki

RolChat dostavlja dogodke vašim sistemom kot podpisane zahteve HTTP POST. Ta stran opisuje webhooke vtičnikov; webhooki, ki jih pošlje pravilo Avtomatizacije, se razlikujejo po ponovitvah, času čakanja in zamenjavi skrivnosti, glejte Webhooki avtomatizacije. Ista pravila veljajo v nasprotni smeri, ko vaš sistem, vtičnik ali ponudnik pošilja podatke v RolChat. Vsako dostavo preverite v spodnjem vrstnem redu, preden se nanjo odzovete.

Kako je videti dostava

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

Glava	Pomen
X-RolChat-Timestamp	Sekunde Unix ob pošiljanju. Del podpisanega sporočila.
X-RolChat-Signature	sha256=<hex>. Predpona navaja algoritem, da ga je mogoče pozneje spremeniti.
X-RolChat-Nonce	ULID, edinstven za to zahtevo HTTP. Ponovni poskus dobi nov nonce.
X-RolChat-Event-Id	Lasten ID dogodka. Pri ponovnih poskusih se ne spremeni; uporabite ga za odstranjevanje dvojnikov.

Odhodne dostave gredo samo na končne točke HTTPS. URL HTTP je zavrnjen ob ustvarjanju naročnine.

Podpis

Podpisano sporočilo je časovni žig, dobesedna pika in surovo telo zahteve, bajt za bajtom:

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

Podpišite bajte, ki ste jih prejeli, ne ponovno serializirane kopije razčlenjenega JSON. Spremembe presledkov ali vrstnega reda ključev pokvarijo podpis. SHA-256 je edini sprejeti algoritem.

Dejanje avtomatizacije „Pošlji zahtevo HTTP“

Zahteve, ki jih pošlje dejanje HTTP modula Avtomatizacija, so podpisane z dvema glavama. X-RolChat-Signature je sha256= plus HMAC-SHA256 samo telesa. X-RolChat-Signature-V2 je HMAC-SHA256 od <timestamp>.<body>, torej shema, opisana zgoraj, z X-RolChat-Timestamp kot časovnim žigom. Preverjajte glavo V2; glava samo s telesom ne varuje pred ponovnim predvajanjem zahteve. Te zahteve ne vsebujejo X-RolChat-Nonce in X-RolChat-Event-Id; vsi poskusi ene dostave nosijo isti X-RolChat-Delivery-Id in lastno številko v X-RolChat-Attempt, zato preskočite preverjanje nonce in deduplicirajte po X-RolChat-Delivery-Id. Vzorci preverjanja berejo X-RolChat-Signature: pri zahtevah avtomatizacije berite X-RolChat-Signature-V2.

Preverjanje dostave

Teh pet preverjanj opravite po vrsti. Primeri v jezikih Python, Node.js, Go, Ruby in PHP so na strani primeri preverjanja.

1. Svežina. Zavrnite, če je |now − X-RolChat-Timestamp| > 300 sekund (400). Pet minut dopušča razliko med urami, prestrežena zahteva pa je po tem času neuporabna. Strežnik sinhronizirajte prek NTP.
2. Podpis. Izračunajte pričakovano vrednost in jo primerjajte v konstantnem času (hmac.compare_digest, crypto.timingSafeEqual, hash_equals). Ob neujemanju zavrnite z 401. Navadna primerjava nizov razkriva podatke prek časa izvajanja in ni sprejemljiva.
3. Nonce. Shranite X-RolChat-Nonce s TTL 10 minut z atomskim zapisom, če ključ ne obstaja (SET NX EX 600). Če že obstaja, zavrnite z 409: zahteva je ponovitev. Če shramba za nonce ne deluje, varno zavrnite z 503, da RolChat poskusi znova; nikoli ne preidite na „sprejmi“.
4. Razčlenite telo šele zdaj.
5. Odstranite dvojnike po ID-ju dogodka. Ponovni poskusi nosijo nov nonce, a isti X-RolChat-Event-Id. Če ste ta ID obdelali v zadnjih sedmih dneh, odgovorite z 200 brez ponovne obdelave.

Odgovorite z 2xx, takoj ko je dostava varno sprejeta; delo opravite asinhrono. RolChat na odgovor čaka 15 sekund.

Skrivnosti

• Skrivnost webhooka je 64 naključnih bajtov, kodiranih v base64url (približno 86 znakov). Ustvari se ob ustvarjanju naročnine ali vtičnika in je prikazana samo enkrat.
• Shranite jo v svoj trezor ali spremenljivko okolja; RolChat hrani samo šifrirano kopijo.
• Menjava je priporočena po 90 dneh; izdelek prikaže opomnik, vendar naročnine zaradi opustitve menjave nikoli ne onemogoči.
• Menjava uporablja obdobje prekrivanja: po POST /api/v1/plugins/{id}/webhook-secret/rotate sedem dni veljata stara in nova skrivnost, nove dostave so podpisane z novo, stara pa se po poteku obdobja izbriše. Ob menjavi se nič ne pokvari.
• Če skrivnost uide, jo POST /api/v1/plugins/{id}/webhook-secret/revoke takoj razveljavi, izda novo, pošlje e-pošto skrbnikom računa in zapiše vnos v revizijo.

Ponovni poskusi in nedostavljiva sporočila

Odgovor, ki ni 2xx, ali omrežna napaka načrtuje ponovni poskus:

Poskus	Zamik po prejšnjem
1	takoj
2	15 sekund
3	1 minuta
4	5 minut
5	30 minut
6	2 uri
7	8 ur
8	24 ur

408, 429, 5xx in omrežne napake se ponovijo. 400, 401, 403, 404 in 410 ne: dostava gre takoj v čakalno vrsto nedostavljivih sporočil, ker ponovni poskus zavrnjenega podpisa ali manjkajoče končne točke ne more pomagati. Po osmih neuspešnih poskusih gre dostava prav tako v čakalno vrsto nedostavljivih sporočil.

Nedostavljiva sporočila se hranijo 30 dni in so vidna v Nastavitve → Vtičniki → {plugin} → Dnevnik webhookov → DLQ, kjer jih lahko skrbnik znova pošlje (POST /api/v1/plugins/{id}/webhook-dlq/{entry_id}/replay).

Omejitve

• Odhodno telo: privzeto 1 MB (nastavljivo za vsak vtičnik). Dohodno telo v RolChat: 5 MB. Večje vrne 413.
• Vtičnik lahko navede allowed_source_ips; RolChat ta seznam dovoljenih uporabi pred preverjanjem.
• Kot dodatno preverjanje se lahko zanesete na uporabniškega agenta RolChat-Webhook/1.0. To ni varnostni ukrep.

Dohodni webhooki v RolChat

Ponudniki pošiljajo podatke v RolChat na /api/v1/webhooks/{category}/{adapter} z lastnimi shemami podpisov (Twilio, Telnyx, Bandwidth, Meta za WhatsApp, Stripe). Vsak adapter preveri podpis svojega ponudnika, normalizira vsebino in jo znova objavi na notranjem vodilu dogodkov s podpisom RolChat. Vaš lastni sistem lahko pošilja podatke v RolChat z istimi glavami X-RolChat-*, opisanimi zgoraj, podpisanimi s skrivnostjo vtičnika, ki mu pripada končna točka.

Webhooki avtomatizacije

Dejanje Pošlji zahtevo HTTP modula Avtomatizacija ima lastna pravila dostave:

• Ena skrivnost na račun. Prikažete ali zamenjate jo na zaslonu Avtomatizacije (Lastnik in Skrbnik). Zamenjava velja takoj: okna prekrivanja ni, stara skrivnost preneha veljati nemudoma, zato najprej posodobite prejemnika ali sprejmite kratko vrzel.
• Čas čakanja: RolChat čaka na odgovor 10 sekund.
• Ponovitve: skupaj največ 6 poskusov. Premor pred 2. poskusom je 30 sekund, nato približno 2 minuti, 8 minut, 32 minut in 2 uri 8 minut, vsak z odstopanjem do 20 %. En premor nikoli ne preseže 6 ur.
• Kaj se ponovi: omrežne napake, prekoračitve časa, 5xx, 408, 425 in 429. Drugi odgovori 4xx, blokiran naslov ali prevelik prenos se ne ponovijo: dostava gre neposredno v vrsto nedostavljivih sporočil, kot tudi po zadnjem neuspelem poskusu.
• Glave: X-RolChat-Signature, X-RolChat-Signature-V2, X-RolChat-Timestamp, X-RolChat-Delivery-Id, X-RolChat-Attempt.

Preizkušanje prejemnika

POST /api/v1/webhooks/test-signature pošlje sintetični podpisani dogodek na končno točko klicočega vtičnika, da lahko svojo implementacijo preverite od začetka do konca, preden pride pravi promet.

Pogoste napake

• Preverjanje glede na razčlenjen in ponovno kodiran JSON namesto surovih bajtov.
• Primerjava podpisov z ==.
• Odstranjevanje dvojnikov po nonce (vsak ponovni poskus ima novega) namesto po ID-ju dogodka.
• Ura, ki odstopa za več kot pet minut.
• Počasno delo pred odgovorom, zaradi česar pride do poteka po 15 sekundah in isti dogodek prispe znova.