Webhook-uri

RolChat livrează evenimente către sistemele tale ca cereri HTTP POST semnate. Această pagină descrie webhookurile pluginurilor; webhookurile trimise de o regulă de Automatizare diferă prin reîncercări, timpul de așteptare și rotirea secretului, vezi Webhookuri de automatizare. Aceleași reguli se aplică și în sens invers, când sistemul tău, un plugin sau un furnizor trimite date către RolChat. Verifică fiecare livrare în ordinea de mai jos înainte să acționezi pe baza ei.

Cum arată o livrare

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

Antet	Semnificație
X-RolChat-Timestamp	Secunde Unix la momentul trimiterii. Face parte din mesajul semnat.
X-RolChat-Signature	sha256=<hex>. Prefixul indică algoritmul, ca acesta să poată fi schimbat ulterior.
X-RolChat-Nonce	Un ULID unic pentru această cerere HTTP. O reîncercare primește un nonce nou.
X-RolChat-Event-Id	ID-ul propriu al evenimentului. Rămâne același la reîncercări; folosește-l pentru eliminarea duplicatelor.

Livrările sunt trimise doar către endpointuri HTTPS. Un URL HTTP este respins la crearea abonamentului.

Semnătura

Mesajul semnat este marcajul de timp, un punct literal și corpul brut al cererii, octet cu octet:

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

Semnează octeții primiți, nu o copie reserializată a JSON-ului parsat. Schimbările de spații sau de ordine a cheilor invalidează semnătura. SHA-256 este singurul algoritm acceptat.

Acțiunea de automatizare „Trimite cerere HTTP”

Cererile trimise de acțiunea HTTP a modulului Automatizare sunt semnate cu două antete. X-RolChat-Signature este sha256= plus HMAC-SHA256 doar al corpului. X-RolChat-Signature-V2 este HMAC-SHA256 al <timestamp>.<body>, schema descrisă mai sus, cu X-RolChat-Timestamp ca marcaj de timp. Verifică antetul V2; antetul doar pentru corp nu protejează împotriva unei cereri retrimise. Aceste cereri nu au X-RolChat-Nonce și nici X-RolChat-Event-Id; toate încercările unei aceleiași livrări poartă același X-RolChat-Delivery-Id și propriul număr în X-RolChat-Attempt, deci sari peste verificarea de nonce și deduplică după X-RolChat-Delivery-Id. Exemplele de verificare citesc X-RolChat-Signature: pentru cererile de automatizare citește în schimb X-RolChat-Signature-V2.

Verificarea unei livrări

Fă aceste cinci verificări în ordine. Exemple în Python, Node.js, Go, Ruby și PHP găsești pe pagina Exemple de verificare.

1. Prospețime. Respinge dacă |now − X-RolChat-Timestamp| > 300 secunde (400). Cinci minute tolerează decalajul ceasurilor și fac inutilă după acest interval o cerere interceptată. Ține serverul sincronizat prin NTP.
2. Semnătura. Calculează valoarea așteptată și compar-o cu o comparație în timp constant (hmac.compare_digest, crypto.timingSafeEqual, hash_equals). Respinge cu 401 dacă nu se potrivesc. O comparație simplă de șiruri dezvăluie informații prin timp și nu este acceptabilă.
3. Nonce. Stochează X-RolChat-Nonce cu un TTL de 10 minute, folosind o setare atomică doar dacă nu există (SET NX EX 600). Dacă există deja, respinge cu 409: cererea este o reluare. Dacă depozitul de nonce-uri nu funcționează, eșuează în mod sigur cu 503, ca RolChat să reîncerce; nu trece niciodată la „acceptă”.
4. Parsează corpul abia acum.
5. Elimină duplicatele după ID-ul evenimentului. Reîncercările au un nonce nou, dar același X-RolChat-Event-Id. Dacă ai procesat acel ID în ultimele șapte zile, răspunde 200 fără să procesezi din nou.

Răspunde 2xx imediat ce livrarea a fost acceptată în siguranță; fă procesarea asincron. RolChat așteaptă un răspuns 15 secunde.

Secrete

• Un secret de webhook are 64 de octeți aleatori, codificați base64url (aproximativ 86 de caractere). Este generat la crearea abonamentului sau a pluginului și afișat o singură dată.
• Păstrează-l în propriul seif sau în variabilele de mediu; RolChat păstrează doar o copie criptată.
• Rotirea este recomandată după 90 de zile; produsul afișează un memento, dar nu dezactivează niciodată un abonament pentru că nu a fost rotit.
• Rotirea folosește o fereastră de suprapunere: după POST /api/v1/plugins/{id}/webhook-secret/rotate, atât secretul vechi, cât și cel nou sunt valabile timp de șapte zile, livrările noi sunt semnate cu cel nou, iar cel vechi este șters după fereastră. Nimic nu se strică în momentul rotirii.
• Dacă un secret este compromis, POST /api/v1/plugins/{id}/webhook-secret/revoke îl invalidează imediat, emite unul nou, trimite un e-mail administratorilor contului și scrie o intrare de audit.

Reîncercări și mesaje nelivrate

Un răspuns non-2xx sau un eșec de rețea programează o reîncercare:

Încercare	Întârziere după cea anterioară
1	imediat
2	15 secunde
3	1 minut
4	5 minute
5	30 de minute
6	2 ore
7	8 ore
8	24 de ore

408, 429, 5xx și erorile de rețea sunt reîncercate. 400, 401, 403, 404 și 410 nu sunt: livrarea ajunge direct în coada de mesaje nelivrate, deoarece reîncercarea unei semnături respinse sau a unui endpoint inexistent nu poate ajuta. După opt încercări eșuate, livrarea ajunge de asemenea în coada de mesaje nelivrate.

Mesajele nelivrate sunt păstrate 30 de zile și sunt vizibile în Setări → Pluginuri → {plugin} → Jurnalul webhook-urilor → DLQ, unde un administrator poate relua unul (POST /api/v1/plugins/{id}/webhook-dlq/{entry_id}/replay).

Limite

• Corpul trimis: 1 MB implicit (configurabil per plugin). Corpul primit de RolChat: 5 MB. Peste aceste valori, 413.
• Un plugin poate declara allowed_source_ips; RolChat aplică această listă de IP-uri permise înainte de verificare.
• Poți verifica user agentul RolChat-Webhook/1.0 ca test suplimentar de coerență. Nu este un mecanism de securitate.

Webhook-uri primite de RolChat

Furnizorii trimit date către RolChat la /api/v1/webhooks/{category}/{adapter}, folosind propriile scheme de semnare (Twilio, Telnyx, Bandwidth, Meta pentru WhatsApp, Stripe). Fiecare adaptor verifică semnătura furnizorului său, normalizează conținutul și îl republică pe magistrala internă de evenimente cu o semnătură RolChat. Propriul tău sistem poate trimite date către RolChat cu aceleași antete X-RolChat-* descrise mai sus, semnate cu secretul pluginului care deține endpointul.

Webhookuri de automatizare

Acțiunea Trimite cerere HTTP a modulului Automatizare are reguli proprii de livrare:

• Un secret per cont. Afișează-l sau rotește-l pe ecranul Automatizare (Proprietar și Admin). Rotirea are efect imediat: nu există o fereastră de suprapunere, vechiul secret nu mai este verificat pe loc, așa că actualizează mai întâi receptorul sau acceptă o scurtă pauză.
• Timp de așteptare: RolChat așteaptă 10 secunde un răspuns.
• Reîncercări: cel mult 6 încercări în total. Pauza înainte de încercarea 2 este de 30 de secunde, apoi de circa 2 minute, 8 minute, 32 de minute și 2 ore 8 minute, fiecare variind cu până la 20 %. O singură pauză nu depășește niciodată 6 ore.
• Ce se reîncearcă: erori de rețea, depășiri de timp, 5xx, 408, 425 și 429. Alte răspunsuri 4xx, o adresă blocată sau un corp prea mare nu se reîncearcă: livrarea merge direct în coada mesajelor eșuate, la fel ca după ultima încercare eșuată.
• Antete: X-RolChat-Signature, X-RolChat-Signature-V2, X-RolChat-Timestamp, X-RolChat-Delivery-Id, X-RolChat-Attempt.

Testarea receptorului

POST /api/v1/webhooks/test-signature trimite un eveniment semnat sintetic către endpointul pluginului apelant, ca să-ți poți verifica implementarea cap-coadă înainte să sosească traficul real.

Greșeli frecvente

• Verificarea pe baza JSON-ului parsat și recodificat, în loc de octeții bruți.
• Folosirea == pentru compararea semnăturilor.
• Eliminarea duplicatelor după nonce (fiecare reîncercare are unul nou) în loc de ID-ul evenimentului.
• Un ceas decalat cu mai mult de cinci minute.
• Procesare lentă înainte de răspuns, urmată de depășirea timpului de 15 secunde și primirea din nou a aceluiași eveniment.