Webhooks

RolChat piegādā notikumus jūsu sistēmām kā parakstītus HTTP POST pieprasījumus. Šī lapa apraksta spraudņu webhookus; webhooki, ko sūta Automatizācijas noteikums, atšķiras ar atkārtojumiem, gaidīšanas laiku un noslēpuma maiņu, skatiet Automatizācijas webhooki. Tie paši noteikumi ir spēkā pretējā virzienā, kad jūsu sistēma, spraudnis vai pakalpojumu sniedzējs sūta datus uz RolChat. Pārbaudiet katru piegādi tālāk norādītajā secībā, pirms uz to reaģējat.

Kā izskatās piegāde

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

Galvene	Nozīme
X-RolChat-Timestamp	Unix sekundes nosūtīšanas brīdī. Parakstītā ziņojuma daļa.
X-RolChat-Signature	sha256=<hex>. Prefikss nosauc algoritmu, lai to vēlāk varētu mainīt.
X-RolChat-Nonce	ULID, kas ir unikāls šim HTTP pieprasījumam. Atkārtojums saņem jaunu nonce.
X-RolChat-Event-Id	Paša notikuma ID. Nemainās atkārtojumos; izmantojiet to dublikātu novēršanai.

Izejošās piegādes notiek tikai uz HTTPS galapunktiem. HTTP URL tiek noraidīts, veidojot abonementu.

Paraksts

Parakstītais ziņojums ir laika zīmogs, burtisks punkts un neapstrādāts pieprasījuma saturs, baits pa baitam:

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

Parakstiet saņemtos baitus, nevis parsētā JSON atkārtoti serializētu kopiju. Atstarpju vai atslēgu secības izmaiņas sabojā parakstu. SHA-256 ir vienīgais pieņemtais algoritms.

Automatizācijas darbība „Sūtīt HTTP pieprasījumu“

Pieprasījumi, ko sūta moduļa Automatizācija HTTP darbība, tiek parakstīti ar divām galvenēm. X-RolChat-Signature ir sha256= plus tikai satura HMAC-SHA256. X-RolChat-Signature-V2 ir <timestamp>.<body> HMAC-SHA256, proti, iepriekš aprakstītā shēma ar X-RolChat-Timestamp kā laika zīmogu. Pārbaudiet V2 galveni; galvene tikai ar saturu neaizsargā pret atkārtoti nosūtītu pieprasījumu. Šiem pieprasījumiem nav X-RolChat-Nonce un X-RolChat-Event-Id; katrs vienas piegādes mēģinājums nes to pašu X-RolChat-Delivery-Id un savu numuru X-RolChat-Attempt, tāpēc nonce pārbaudi izlaidiet un dublikātus noņemiet pēc X-RolChat-Delivery-Id. Pārbaudes piemēri lasa X-RolChat-Signature: automatizācijas pieprasījumiem tā vietā lasiet X-RolChat-Signature-V2.

Piegādes pārbaude

Veiciet šīs piecas pārbaudes secīgi. Paraugi Python, Node.js, Go, Ruby un PHP valodā ir lapā Pārbaudes paraugi.

1. Svaigums. Noraidiet, ja |now − X-RolChat-Timestamp| > 300 sekundes (400). Piecas minūtes pieļauj pulksteņu nobīdi un padara pārtvertu pieprasījumu pēc tam bezvērtīgu. Uzturiet savu serveri sinhronizētu ar NTP.
2. Paraksts. Aprēķiniet sagaidāmo vērtību un salīdziniet ar konstanta laika salīdzināšanu (hmac.compare_digest, crypto.timingSafeEqual, hash_equals). Neatbilstības gadījumā noraidiet ar 401. Parasta virkņu salīdzināšana nopludina laika informāciju un nav pieņemama.
3. Nonce. Saglabājiet X-RolChat-Nonce ar 10 minūšu TTL, izmantojot atomāru iestatīšanu, ja nav (SET NX EX 600). Ja tas jau pastāv, noraidiet ar 409: pieprasījums ir atkārtojums. Ja jūsu nonce krātuve nedarbojas, atsakiet droši ar 503, lai RolChat atkārto; nekad nepārejiet uz “pieņemt”.
4. Parsējiet saturu tikai tagad.
5. Novērsiet dublikātus pēc notikuma ID. Atkārtojumiem ir jauns nonce, bet tas pats X-RolChat-Event-Id. Ja šo ID esat apstrādājis pēdējo septiņu dienu laikā, atbildiet ar 200, neapstrādājot atkārtoti.

Atbildiet ar 2xx, tiklīdz piegāde ir droši pieņemta; darbu veiciet asinhroni. RolChat gaida atbildi 15 sekundes.

Noslēpumi

• Webhook noslēpums ir 64 nejauši baiti base64url kodējumā (apmēram 86 rakstzīmes). Tas tiek ģenerēts, veidojot abonementu vai spraudni, un parādīts vienreiz.
• Glabājiet to savā glabātavā vai vides mainīgajos; RolChat glabā tikai šifrētu kopiju.
• Rotāciju ieteicams veikt pēc 90 dienām; produkts rāda atgādinājumu, bet nekad neatspējo abonementu tāpēc, ka rotācija nav veikta.
• Rotācija izmanto pārklāšanās logu: pēc POST /api/v1/plugins/{id}/webhook-secret/rotate gan vecais, gan jaunais noslēpums septiņas dienas iztur pārbaudi, jaunas piegādes tiek parakstītas ar jauno, un vecais tiek dzēsts pēc loga beigām. Rotācijas brīdī nekas nesabojājas.
• Ja noslēpums noplūst, POST /api/v1/plugins/{id}/webhook-secret/revoke to nekavējoties anulē, izsniedz jaunu, nosūta e-pastu konta administratoriem un ieraksta audita ierakstu.

Atkārtojumi un nepiegādātās vēstules

Atbilde, kas nav 2xx, vai tīkla kļūme ieplāno atkārtojumu:

Mēģinājums	Aizture pēc iepriekšējā
1	nekavējoties
2	15 sekundes
3	1 minūte
4	5 minūtes
5	30 minūtes
6	2 stundas
7	8 stundas
8	24 stundas

408, 429, 5xx un tīkla kļūdas tiek atkārtotas. 400, 401, 403, 404 un 410 netiek: piegāde nonāk tieši nepiegādāto vēstuļu rindā, jo noraidīta paraksta vai trūkstoša galapunkta atkārtošana nevar palīdzēt. Pēc astoņiem neveiksmīgiem mēģinājumiem piegāde arī nonāk nepiegādāto vēstuļu rindā.

Nepiegādātās vēstules tiek glabātas 30 dienas un ir redzamas sadaļā Iestatījumi → Spraudņi → {plugin} → Webhook žurnāls → DLQ, kur administrators var kādu no tām atkārtot (POST /api/v1/plugins/{id}/webhook-dlq/{entry_id}/replay).

Ierobežojumi

• Izejošais saturs: pēc noklusējuma 1 MB (konfigurējams katram spraudnim). Ienākošais saturs RolChat: 5 MB. Lielāks ir 413.
• Spraudnis var deklarēt allowed_source_ips; RolChat piemēro šo atļauto sarakstu pirms pārbaudes.
• Kā papildu saprāta pārbaudi varat piesaistīties lietotāja aģentam RolChat-Webhook/1.0. Tas nav drošības mehānisms.

Ienākošie webhook RolChat

Pakalpojumu sniedzēji sūta datus uz RolChat adresē /api/v1/webhooks/{category}/{adapter}, izmantojot savas parakstu shēmas (Twilio, Telnyx, Bandwidth, Meta priekš WhatsApp, Stripe). Katrs adapteris pārbauda sava pakalpojumu sniedzēja parakstu, normalizē saturu un atkārtoti publicē to iekšējā notikumu kopnē ar RolChat parakstu. Jūsu pašu sistēma var sūtīt datus uz RolChat ar tām pašām iepriekš aprakstītajām X-RolChat-* galvenēm, parakstītām ar tā spraudņa noslēpumu, kuram pieder galapunkts.

Automatizācijas webhooki

Moduļa Automatizācija darbībai Sūtīt HTTP pieprasījumu ir savi piegādes noteikumi:

• Viens noslēpums katram kontam. Parādiet vai nomainiet to Automatizācijas ekrānā (Īpašnieks un Administrators). Maiņa stājas spēkā uzreiz: pārklāšanās loga nav, vecais noslēpums pārstāj derēt nekavējoties, tāpēc vispirms atjauniniet saņēmēju vai samierinieties ar īsu pārtraukumu.
• Gaidīšanas laiks: RolChat gaida atbildi 10 sekundes.
• Atkārtojumi: kopā līdz 6 mēģinājumiem. Pauze pirms 2. mēģinājuma ir 30 sekundes, pēc tam aptuveni 2 minūtes, 8 minūtes, 32 minūtes un 2 stundas 8 minūtes, katra ar novirzi līdz 20 %. Viena pauze nekad nepārsniedz 6 stundas.
• Kas tiek atkārtots: tīkla kļūdas, noildzes, 5xx, 408, 425 un 429. Citas 4xx atbildes, bloķēta adrese vai pārāk liels saturs netiek atkārtoti: piegāde uzreiz nonāk nepiegādāto vēstuļu rindā, tāpat kā pēc pēdējā neizdevušā mēģinājuma.
• Galvenes: X-RolChat-Signature, X-RolChat-Signature-V2, X-RolChat-Timestamp, X-RolChat-Delivery-Id, X-RolChat-Attempt.

Jūsu saņēmēja testēšana

POST /api/v1/webhooks/test-signature nosūta sintētisku parakstītu notikumu uz izsaucošā spraudņa galapunktu, lai jūs varētu pārbaudīt savu realizāciju no sākuma līdz beigām, pirms pienāk reāla datplūsma.

Biežākās kļūdas

• Pārbaude pret parsētu un atkārtoti kodētu JSON, nevis neapstrādātiem baitiem.
• == izmantošana parakstu salīdzināšanai.
• Dublikātu novēršana pēc nonce (katram atkārtojumam ir jauns), nevis pēc notikuma ID.
• Pulkstenis, kas atšķiras vairāk nekā par piecām minūtēm.
• Lēna darba veikšana pirms atbildes, pēc tam noildze pēc 15 sekundēm un tā paša notikuma saņemšana vēlreiz.