Veebihaagid

RolChat toimetab sündmused sinu süsteemidesse allkirjastatud HTTP POST-päringutena. See leht kirjeldab pistikprogrammide veebihaake; Automatiseerimise reegli saadetud veebihaagid erinevad korduskatsete, ooteaja ja saladuse vahetamise poolest, vt Automatiseerimise veebihaagid. Samad reeglid kehtivad vastupidises suunas, kui sinu süsteem, pistikprogramm või pakkuja postitab RolChati. Kontrolli iga edastust allpool toodud järjekorras, enne kui selle põhjal tegutsed.

Milline edastus välja näeb

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

Päis	Tähendus
X-RolChat-Timestamp	Unixi sekundid saatmise hetkel. Osa allkirjastatud sõnumist.
X-RolChat-Signature	sha256=<hex>. Eesliide nimetab algoritmi, et seda saaks hiljem muuta.
X-RolChat-Nonce	Sellele HTTP-päringule unikaalne ULID. Korduskatse saab uue nonce’i.
X-RolChat-Event-Id	Sündmuse enda ID. Püsib korduskatsete vahel samana; kasuta seda duplikaatide eemaldamiseks.

Väljaminevad edastused lähevad ainult HTTPS-lõpp-punktidele. HTTP-URL lükatakse tellimuse loomisel tagasi.

Allkiri

Allkirjastatud sõnum on ajatempel, sõna-sõnaline punkt ja töötlemata päringu sisu, bait-baidilt:

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

Allkirjasta saadud baidid, mitte parsitud JSON-i uuesti serialiseeritud koopia. Tühikute või võtmete järjekorra muutused rikuvad allkirja. SHA-256 on ainus aktsepteeritud algoritm.

Automatiseerimise tegevus “Saada HTTP-päring”

Mooduli Automatiseerimine HTTP-tegevuse saadetud päringud allkirjastatakse kahe päisega. X-RolChat-Signature on sha256= ja ainult sisu HMAC-SHA256. X-RolChat-Signature-V2 on <timestamp>.<body> HMAC-SHA256, st eespool kirjeldatud skeem, kus ajatemplina on X-RolChat-Timestamp. Kontrollige V2-päist; ainult sisu päis ei kaitse kordusrünnaku eest. Neis päringutes pole X-RolChat-Nonce ega X-RolChat-Event-Id; ühe edastuse kõik katsed kannavad sama X-RolChat-Delivery-Id ja oma numbrit päises X-RolChat-Attempt, seega jäta nonce’i kontroll vahele ja eemalda duplikaadid X-RolChat-Delivery-Id järgi. Kontrollinäited loevad X-RolChat-Signature: automatiseerimispäringute puhul lugege selle asemel X-RolChat-Signature-V2.

Edastuse kontrollimine

Tee need viis kontrolli järjekorras. Näited Pythonis, Node.js-is, Go-s, Ruby’s ja PHP-s on lehel kontrollinäited.

1. Värskus. Lükka tagasi, kui |now − X-RolChat-Timestamp| > 300 sekundit (400). Viis minutit talub kellade nihet ja muudab pealtkuulatud päringu pärast seda väärtusetuks. Hoia oma server NTP-ga sünkroonis.
2. Allkiri. Arvuta oodatav väärtus ja võrdle seda konstantse ajaga võrdlusega (hmac.compare_digest, crypto.timingSafeEqual, hash_equals). Mittevastavuse korral lükka tagasi koodiga 401. Tavaline stringivõrdlus lekitab ajastusinfot ega ole vastuvõetav.
3. Nonce. Salvesta X-RolChat-Nonce 10-minutilise TTL-iga, kasutades atomaarset lisamist ainult puudumisel (SET NX EX 600). Kui see on juba olemas, lükka tagasi koodiga 409: päring on taasesitus. Kui sinu nonce’ide hoidla ei tööta, keeldu koodiga 503, et RolChat prooviks uuesti; ära kunagi lange tagasi “aktsepteerimisele”.
4. Parsi sisu alles nüüd.
5. Eemalda duplikaadid sündmuse ID järgi. Korduskatsed kannavad uut nonce’i, kuid sama X-RolChat-Event-Id. Kui oled seda ID-d viimase seitsme päeva jooksul töödelnud, vasta 200 ilma uuesti töötlemata.

Vasta 2xx niipea, kui edastus on turvaliselt vastu võetud; tee töö asünkroonselt. RolChat ootab vastust 15 sekundit.

Saladused

• Veebihaagi saladus on 64 juhuslikku baiti base64url-kodeeringus (umbes 86 märki). See genereeritakse tellimuse või pistikprogrammi loomisel ja seda näidatakse üks kord.
• Hoia seda oma hoidlas või keskkonnas; RolChat säilitab ainult krüpteeritud koopia.
• Vahetamine on soovitatav 90 päeva järel; toode näitab meeldetuletust, kuid ei keela kunagi tellimust vahetamata jätmise pärast.
• Vahetamine kasutab kattuvusakent: pärast käsku POST /api/v1/plugins/{id}/webhook-secret/rotate kehtivad kontrollimisel seitse päeva nii vana kui ka uus saladus, uued edastused allkirjastatakse uuega ja vana kustutatakse pärast akna lõppu. Vahetamise hetkel ei lähe midagi katki.
• Kui saladus lekib, muudab POST /api/v1/plugins/{id}/webhook-secret/revoke selle kohe kehtetuks, väljastab uue, saadab konto administraatoritele e-kirja ja kirjutab auditikirje.

Korduskatsed ja kohaletoimetamata sõnumid

Mitte-2xx vastus või võrgutõrge ajastab korduskatse:

Katse	Viivitus pärast eelmist
1	kohe
2	15 sekundit
3	1 minut
4	5 minutit
5	30 minutit
6	2 tundi
7	8 tundi
8	24 tundi

Koode 408, 429, 5xx ja võrguvigu proovitakse uuesti. Koode 400, 401, 403, 404 ja 410 ei proovita: edastus läheb otse kohaletoimetamata sõnumite järjekorda, sest tagasilükatud allkirja või puuduva lõpp-punkti uuesti proovimine ei aita. Pärast kaheksat ebaõnnestunud katset läheb edastus samuti kohaletoimetamata sõnumite järjekorda.

Kohaletoimetamata sõnumeid säilitatakse 30 päeva ja need on nähtavad jaotises Seaded → Pistikprogrammid → {plugin} → Veebihaakide logi → DLQ, kus administraator saab ühe uuesti esitada (POST /api/v1/plugins/{id}/webhook-dlq/{entry_id}/replay).

Piirangud

• Väljamineva sisu maht: vaikimisi 1 MB (seadistatav pistikprogrammi kaupa). RolChati sissetuleva sisu maht: 5 MB. Suurem on 413.
• Pistikprogramm võib deklareerida allowed_source_ips; RolChat rakendab seda lubade loendit enne kontrollimist.
• Lisakontrollina võid kinnituda kasutajaagendile RolChat-Webhook/1.0. See ei ole turvameede.

Sissetulevad veebihaagid RolChati

Pakkujad postitavad RolChati aadressile /api/v1/webhooks/{category}/{adapter}, kasutades oma allkirjaskeeme (Twilio, Telnyx, Bandwidth, Meta WhatsAppi jaoks, Stripe). Iga adapter kontrollib oma pakkuja allkirja, normaliseerib sisu ja avaldab selle uuesti sisemisel sündmustesiinil RolChati allkirjaga. Sinu enda süsteem saab RolChati postitada samade ülalkirjeldatud X-RolChat-* päistega, allkirjastatuna lõpp-punkti omava pistikprogrammi saladusega.

Automatiseerimise veebihaagid

Mooduli Automatiseerimine tegevusel Saada HTTP-päring on omad edastusreeglid:

• Üks saladus konto kohta. Vaata või vaheta seda Automatiseerimise vaates (omanik ja administraator). Vahetus jõustub kohe: kattuvat akent pole, vana saladus lakkab kohe kehtimast, seega uuenda esmalt oma vastuvõtjat või aktsepteeri lühike vahe.
• Ooteaeg: RolChat ootab vastust 10 sekundit.
• Korduskatsed: kokku kuni 6 katset. Paus enne katset 2 on 30 sekundit, seejärel umbes 2 minutit, 8 minutit, 32 minutit ja 2 tundi 8 minutit, igaüks kuni 20 % varieeruvusega. Üksik paus ei ületa kunagi 6 tundi.
• Mida korratakse: võrguvead, ajalõpud, 5xx, 408, 425 ja 429. Muid 4xx vastuseid, blokeeritud aadressi või liiga suurt bodyt ei korrata: edastus läheb otse kohaletoimetamata sõnumite järjekorda, nagu ka pärast viimast ebaõnnestunud katset.
• Päised: X-RolChat-Signature, X-RolChat-Signature-V2, X-RolChat-Timestamp, X-RolChat-Delivery-Id, X-RolChat-Attempt.

Vastuvõtja testimine

POST /api/v1/webhooks/test-signature saadab sünteetilise allkirjastatud sündmuse väljakutsuva pistikprogrammi lõpp-punkti, et saaksid oma teostust otsast lõpuni kontrollida enne päris liikluse saabumist.

Levinud vead

• Kontrollimine parsitud ja uuesti kodeeritud JSON-i vastu töötlemata baitide asemel.
• == kasutamine allkirjade võrdlemiseks.
• Duplikaatide eemaldamine nonce’i järgi (igal korduskatsel on uus) sündmuse ID asemel.
• Kell, mis on üle viie minuti vale.
• Aeglane töö enne vastamist, mille tulemusel ületatakse 15-sekundiline ajalõpp ja sama sündmus saabub uuesti.