Webhook'ai

RolChat pristato įvykius jūsų sistemoms kaip pasirašytas HTTP POST užklausas. Šis puslapis aprašo įskiepių webhook’us; Automatizavimo taisyklės siunčiami webhook’ai skiriasi pakartojimais, laukimo laiku ir paslapties keitimu, žr. Automatizavimo webhook’ai. Tos pačios taisyklės taikomos ir kita kryptimi, kai jūsų sistema, įskiepis ar tiekėjas siunčia duomenis į RolChat. Prieš imdamiesi veiksmų, patikrinkite kiekvieną pristatymą toliau nurodyta tvarka.

Kaip atrodo pristatymas

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

Antraštė	Reikšmė
`X-RolChat-Timestamp`	Unix sekundės išsiuntimo metu. Pasirašomos žinutės dalis.
`X-RolChat-Signature`	`sha256=<hex>`. Priešdėlis nurodo algoritmą, kad vėliau jį būtų galima pakeisti.
`X-RolChat-Nonce`	ULID, unikalus šiai HTTP užklausai. Pakartojimas gauna naują nonce.
`X-RolChat-Event-Id`	Paties įvykio ID. Nesikeičia pakartojimų metu; naudokite jį dublikatams šalinti.

Siunčiami pristatymai keliauja tik į HTTPS galinius taškus. HTTP URL atmetamas kuriant prenumeratą.

Parašas

Pasirašoma žinutė yra laiko žyma, taškas ir neapdorotas užklausos turinys, baitas po baito:

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

Pasirašykite gautus baitus, o ne iš naujo serializuotą išanalizuoto JSON kopiją. Tarpų ar raktų tvarkos pakeitimai sugadina parašą. SHA-256 yra vienintelis priimamas algoritmas.

Užklausos, siunčiamos Automatizavimo modulio HTTP veiksmu, pasirašomos dviem antraštėmis. X-RolChat-Signature yra sha256= ir tik turinio HMAC-SHA256. X-RolChat-Signature-V2 yra <timestamp>.<body> HMAC-SHA256, t. y. aukščiau aprašyta schema, o laiko žyma yra X-RolChat-Timestamp. Tikrinkite V2 antraštę; antraštė tik pagal turinį neapsaugo nuo pakartotinai siunčiamos užklausos. Šios užklausos neturi X-RolChat-Nonce ir X-RolChat-Event-Id; kiekvienas vieno pristatymo bandymas turi tą patį X-RolChat-Delivery-Id ir savo numerį X-RolChat-Attempt, todėl praleiskite nonce patikrinimą ir deduplikuokite pagal X-RolChat-Delivery-Id. Patikrinimo pavyzdžiuose skaitoma X-RolChat-Signature: automatizavimo užklausoms vietoje jos skaitykite X-RolChat-Signature-V2.

Pristatymo patikrinimas

Atlikite šiuos penkis patikrinimus iš eilės. Pavyzdžiai Python, Node.js, Go, Ruby ir PHP kalbomis pateikti puslapyje patikrinimo pavyzdžiai.

Šviežumas. Atmeskite, jei |now − X-RolChat-Timestamp| > 300 sekundžių (400). Penkios minutės toleruoja laikrodžių neatitikimą, o po jų perimta užklausa tampa bevertė. Laikykite savo serverį sinchronizuotą su NTP.
Parašas. Apskaičiuokite laukiamą reikšmę ir palyginkite ją pastovaus laiko palyginimu (hmac.compare_digest, crypto.timingSafeEqual, hash_equals). Nesutapus atmeskite su 401. Paprastas eilučių palyginimas nutekina laiko informaciją ir yra nepriimtinas.
Nonce. Išsaugokite X-RolChat-Nonce su 10 minučių TTL, naudodami atominį „nustatyti, jei nėra“ (SET NX EX 600). Jei jis jau yra, atmeskite su 409: užklausa yra pakartojimas. Jei jūsų nonce saugykla neveikia, saugiai atmeskite su 503, kad RolChat pakartotų; niekada nepereikite prie „priimti“.
Tik dabar išanalizuokite turinį.
Šalinkite dublikatus pagal įvykio ID. Pakartojimai turi naują nonce, bet tą patį X-RolChat-Event-Id. Jei tą ID apdorojote per pastarąsias septynias dienas, atsakykite 200 neapdorodami iš naujo.

Atsakykite 2xx, kai tik pristatymas saugiai priimtas; darbą atlikite asinchroniškai. RolChat laukia atsakymo 15 sekundžių.

Paslaptys

Webhook’o paslaptis yra 64 atsitiktiniai baitai, užkoduoti base64url (apie 86 simbolius). Ji sugeneruojama kuriant prenumeratą ar įskiepį ir parodoma vieną kartą.
Saugokite ją savo saugykloje arba aplinkos kintamuosiuose; RolChat laiko tik užšifruotą kopiją.
Rekomenduojama keisti po 90 dienų; produktas rodo priminimą, bet niekada neišjungia prenumeratos dėl nepakeistos paslapties.
Keitimas naudoja persidengimo langą: po POST /api/v1/plugins/{id}/webhook-secret/rotate septynias dienas tikrinama ir sena, ir nauja paslaptis, nauji pristatymai pasirašomi nauja, o sena ištrinama pasibaigus langui. Pakeitimo momentu niekas nesugenda.
Jei paslaptis nutekėjo, POST /api/v1/plugins/{id}/webhook-secret/revoke iškart ją panaikina, išduoda naują, išsiunčia el. laišką paskyros administratoriams ir įrašo audito įrašą.

Pakartojimai ir neįteiktos žinutės

Ne 2xx atsakymas arba tinklo klaida suplanuoja pakartojimą:

Bandymas	Delsa po ankstesnio
1	iškart
2	15 sekundžių
3	1 minutė
4	5 minutės
5	30 minučių
6	2 valandos
7	8 valandos
8	24 valandos

408, 429, 5xx ir tinklo klaidos kartojamos. 400, 401, 403, 404 ir 410 nekartojamos: pristatymas iškart patenka į neįteiktų žinučių eilę, nes atmesto parašo ar neegzistuojančio galinio taško pakartojimas negali padėti. Po aštuonių nepavykusių bandymų pristatymas taip pat perkeliamas į neįteiktų žinučių eilę.

Neįteiktos žinutės saugomos 30 dienų ir matomos skiltyje Nustatymai → Įskiepiai → {plugin} → Webhook’ų žurnalas → DLQ, kur administratorius gali vieną iš jų pakartoti (POST /api/v1/plugins/{id}/webhook-dlq/{entry_id}/replay).

Limitai

Siunčiamas turinys: numatytai 1 MB (konfigūruojama kiekvienam įskiepiui). Gaunamas turinys į RolChat: 5 MB. Didesnis yra 413.
Įskiepis gali deklaruoti allowed_source_ips; RolChat taiko šį leidžiamų adresų sąrašą prieš tikrindamas.
Kaip papildomą patikrą galite tikrinti naudotojo agentą RolChat-Webhook/1.0. Tai nėra saugumo priemonė.

Gaunami webhook’ai į RolChat

Tiekėjai siunčia į RolChat adresu /api/v1/webhooks/{category}/{adapter}, naudodami savo parašų schemas (Twilio, Telnyx, Bandwidth, Meta WhatsApp atveju, Stripe). Kiekvienas adapteris patikrina savo tiekėjo parašą, suvienodina turinį ir iš naujo paskelbia jį vidinėje įvykių magistralėje su RolChat parašu. Jūsų sistema gali siųsti į RolChat su tomis pačiomis aukščiau aprašytomis antraštėmis X-RolChat-*, pasirašytomis galinį tašką valdančio įskiepio paslaptimi.

Automatizavimo webhook’ai

Siųsti HTTP užklausą veiksmas Automatizavimo modulyje turi savo pristatymo taisykles:

Viena paslaptis kiekvienai paskyrai. Parodykite ar pakeiskite ją Automatizavimo ekrane (Savininkas ir Administratorius). Keitimas įsigalioja iš karto: persidengimo lango nėra, sena paslaptis nustoja galioti nedelsiant, todėl pirmiausia atnaujinkite gavėją arba susitaikykite su trumpa pertrauka.
Laukimo laikas: RolChat laukia atsakymo 10 sekundžių.
Pakartojimai: iš viso iki 6 bandymų. Pauzė prieš 2 bandymą yra 30 sekundžių, vėliau maždaug 2 minutės, 8 minutės, 32 minutės ir 2 valandos 8 minutės, kiekviena su iki 20 % nuokrypiu. Viena pauzė niekada neviršija 6 valandų.
Kas kartojama: tinklo klaidos, laiko limito viršijimai, 5xx, 408, 425 ir 429. Kiti 4xx atsakymai, užblokuotas adresas ar per didelis turinys nekartojami: pristatymas iš karto patenka į neįteiktų žinučių eilę, kaip ir po paskutinio nepavykusio bandymo.
Antraštės: X-RolChat-Signature, X-RolChat-Signature-V2, X-RolChat-Timestamp, X-RolChat-Delivery-Id, X-RolChat-Attempt.

Gavėjo testavimas

POST /api/v1/webhooks/test-signature išsiunčia sintetinį pasirašytą įvykį į kviečiančio įskiepio galinį tašką, kad galėtumėte patikrinti savo įgyvendinimą nuo pradžios iki galo prieš atkeliaujant tikram srautui.

Dažnos klaidos

Tikrinimas pagal išanalizuotą ir iš naujo užkoduotą JSON, o ne neapdorotus baitus.
Parašų palyginimas naudojant ==.
Dublikatų šalinimas pagal nonce (kiekvienas pakartojimas turi naują), o ne pagal įvykio ID.
Laikrodis, nukrypęs daugiau nei penkias minutes.
Lėtas darbas prieš atsakant, dėl kurio po 15 sekundžių baigiasi laikas ir tas pats įvykis gaunamas vėl.