Webhookok

A RolChat aláírt HTTP POST kérésekként kézbesíti az eseményeket a rendszereidnek. Ez az oldal a plugin webhookokat írja le; az Automatizálás szabályai által küldött webhookok az újrapróbálkozásokban, a várakozási időben és a titkos kulcs cseréjében eltérnek, lásd: Automatizálási webhookok. Ugyanezek a szabályok érvényesek a másik irányban is, amikor a rendszered, egy plugin vagy egy szolgáltató küld adatot a RolChatbe. Minden kézbesítést ellenőrizz az alábbi sorrendben, mielőtt bármit tennél vele.

Hogyan néz ki egy kézbesítés

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

Fejléc	Jelentés
`X-RolChat-Timestamp`	Unix-másodpercek a küldés pillanatában. Az aláírt üzenet része.
`X-RolChat-Signature`	`sha256=<hex>`. Az előtag megnevezi az algoritmust, hogy később változhasson.
`X-RolChat-Nonce`	Erre a HTTP-kérésre egyedi ULID. Egy újrapróbálkozás új nonce-t kap.
`X-RolChat-Event-Id`	Az esemény saját azonosítója. Az újrapróbálkozások során változatlan; ezt használd a duplikátumszűréshez.

A kimenő kézbesítések csak HTTPS-végpontokra mennek. HTTP URL-t a feliratkozás létrehozásakor elutasítunk.

Az aláírás

Az aláírt üzenet az időbélyeg, egy pont karakter és a nyers kéréstörzs, bájtról bájtra:

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

A kapott bájtokat írd alá, ne a feldolgozott JSON újraszerializált másolatát. A szóközök vagy a kulcsok sorrendjének változása tönkreteszi az aláírást. Az egyetlen elfogadott algoritmus a SHA-256.

Az Automatizálás modul HTTP-műveletével küldött kéréseket két fejléc írja alá. Az X-RolChat-Signature értéke sha256= plusz csak a törzs HMAC-SHA256 értéke. Az X-RolChat-Signature-V2 a <timestamp>.<body> HMAC-SHA256 értéke, vagyis a fent leírt séma, időbélyegként az X-RolChat-Timestamp fejléccel. A V2 fejlécet ellenőrizd; a csak a törzset fedő fejléc nem véd az újrajátszott kérés ellen. Ezek a kérések nem tartalmaznak X-RolChat-Nonce és X-RolChat-Event-Id fejlécet; egy kézbesítés minden kísérlete ugyanazt az X-RolChat-Delivery-Id értéket és az X-RolChat-Attempt fejlécben saját sorszámot hordoz, ezért a nonce-ellenőrzést hagyd ki, a duplikációt pedig az X-RolChat-Delivery-Id alapján szűrd. Az ellenőrzési minták az X-RolChat-Signature fejlécet olvassák: az automatizálási kéréseknél helyette az X-RolChat-Signature-V2 fejlécet olvasd.

Egy kézbesítés ellenőrzése

Végezd el ezt az öt ellenőrzést sorrendben. Python, Node.js, Go, Ruby és PHP nyelvű minták az ellenőrzési minták oldalon találhatók.

Frissesség. Utasítsd el, ha |now − X-RolChat-Timestamp| > 300 másodperc (400). Az öt perc elviseli az órák eltérését, és ezután értéktelenné teszi az elfogott kérést. Tartsd a szerveredet NTP-vel szinkronban.
Aláírás. Számítsd ki a várt értéket, és állandó idejű összehasonlítással vesd össze (hmac.compare_digest, crypto.timingSafeEqual, hash_equals). Eltérés esetén utasítsd el 401 válasszal. Az egyszerű karakterlánc-összehasonlítás időzítési információt szivárogtat ki, és nem elfogadható.
Nonce. Tárold az X-RolChat-Nonce értéket 10 perces TTL-lel, atomi „beállítás, ha nem létezik” művelettel (SET NX EX 600). Ha már létezik, utasítsd el 409 válasszal: a kérés visszajátszás. Ha a nonce-tárolód nem elérhető, zárj biztonságosan 503 válasszal, hogy a RolChat újrapróbálkozzon; soha ne engedd át „elfogadásként”.
Dolgozd fel a törzset csak most.
Szűrd a duplikátumokat eseményazonosító alapján. Az újrapróbálkozások új nonce-t, de ugyanazt az X-RolChat-Event-Id értéket hordozzák. Ha az elmúlt hét napban már feldolgoztad ezt az azonosítót, válaszolj 200 kóddal újbóli feldolgozás nélkül.

Válaszolj 2xx kóddal, amint a kézbesítést biztonságosan elfogadtad; a munkát aszinkron módon végezd. A RolChat 15 másodpercig vár a válaszra.

Titkos kulcsok

A webhook titkos kulcsa 64 véletlen bájt base64url kódolásban (körülbelül 86 karakter). A feliratkozás vagy a plugin létrehozásakor generálódik, és egyszer jelenik meg.
Tárold a saját titokkezelődben vagy környezeti változóban; a RolChat csak titkosított másolatot őriz.
90 nap után ajánlott a kulcscsere; a termék emlékeztetőt jelenít meg, de a csere elmaradása miatt soha nem kapcsol ki feliratkozást.
A kulcscsere átfedési időablakot használ: a POST /api/v1/plugins/{id}/webhook-secret/rotate után hét napig a régi és az új kulcs is érvényes, az új kézbesítések már az újjal vannak aláírva, a régit pedig az időablak után töröljük. A csere pillanatában semmi sem romlik el.
Ha egy titkos kulcs kiszivárog, a POST /api/v1/plugins/{id}/webhook-secret/revoke azonnal érvényteleníti, újat állít ki, e-mailt küld a fiók adminisztrátorainak, és auditbejegyzést ír.

Újrapróbálkozások és kézbesíthetetlen üzenetek

A nem 2xx válasz vagy hálózati hiba újrapróbálkozást ütemez:

Kísérlet	Késleltetés az előzőhöz képest
1	azonnal
2	15 másodperc
3	1 perc
4	5 perc
5	30 perc
6	2 óra
7	8 óra
8	24 óra

A 408, 429, 5xx és a hálózati hibák esetén újrapróbálkozunk. A 400, 401, 403, 404 és 410 esetén nem: a kézbesítés egyenesen a kézbesíthetetlen üzenetek várólistájára (DLQ) kerül, mert egy elutasított aláírás vagy egy hiányzó végpont újrapróbálása nem segíthet. Nyolc sikertelen kísérlet után a kézbesítés szintén a DLQ-ba kerül.

A kézbesíthetetlen üzeneteket 30 napig őrizzük, és a Beállítások → Pluginek → {plugin} → Webhooknapló → DLQ menüben láthatók, ahol egy adminisztrátor újrajátszhatja őket (POST /api/v1/plugins/{id}/webhook-dlq/{entry_id}/replay).

Korlátok

Kimenő törzs: alapértelmezés szerint 1 MB (pluginenként konfigurálható). A RolChatbe érkező bejövő törzs: 5 MB. A nagyobb 413 választ kap.
Egy plugin megadhat allowed_source_ips listát; a RolChat ezt az engedélyezési listát az ellenőrzés előtt alkalmazza.
Extra épségellenőrzésként rögzítheted a RolChat-Webhook/1.0 user agentet. Ez nem biztonsági intézkedés.

Bejövő webhookok a RolChatbe

A szolgáltatók a /api/v1/webhooks/{category}/{adapter} címre küldenek a RolChatnek, saját aláírási sémáikkal (Twilio, Telnyx, Bandwidth, Meta a WhatsApphoz, Stripe). Minden adapter ellenőrzi a szolgáltatója aláírását, normalizálja a tartalmat, és RolChat-aláírással újra közzéteszi a belső eseménybuszon. A saját rendszered is küldhet a RolChatnek a fent leírt X-RolChat-* fejlécekkel, a végpontot birtokló plugin titkos kulcsával aláírva.

Automatizálási webhookok

Az Automatizálás modul HTTP-kérés küldése művelete saját kézbesítési szabályokkal rendelkezik:

Fiókonként egy titkos kulcs. Az Automatizálás képernyőn jelenítheted meg vagy cserélheted (Tulajdonos és Adminisztrátor). A csere azonnal érvénybe lép: nincs átfedési időszak, a régi titkos kulcs azonnal megszűnik érvényes lenni, ezért előbb frissítsd a fogadót, vagy fogadj el egy rövid kiesést.
Várakozási idő: a RolChat 10 másodpercig vár a válaszra.
Újrapróbálkozások: összesen legfeljebb 6 kísérlet. A 2. kísérlet előtti szünet 30 másodperc, utána körülbelül 2 perc, 8 perc, 32 perc és 2 óra 8 perc, mindegyik legfeljebb 20 %-kal eltérhet. Egy szünet sem haladja meg a 6 órát.
Mit próbál újra: hálózati hibák, időtúllépések, 5xx, 408, 425 és 429. Más 4xx válaszok, letiltott cím vagy túl nagy törzs esetén nincs újrapróbálkozás: a kézbesítés rögtön a kézbesíthetetlen üzenetek sorába kerül, ahogy az utolsó sikertelen kísérlet után is.
Fejlécek: X-RolChat-Signature, X-RolChat-Signature-V2, X-RolChat-Timestamp, X-RolChat-Delivery-Id, X-RolChat-Attempt.

A fogadóoldal tesztelése

A POST /api/v1/webhooks/test-signature szintetikus, aláírt eseményt küld a hívó plugin végpontjára, így a valós forgalom megérkezése előtt végig ellenőrizheted a megvalósításodat.

Gyakori hibák

Ellenőrzés a feldolgozott és újrakódolt JSON-on a nyers bájtok helyett.
Az aláírások összehasonlítása == operátorral.
Duplikátumszűrés nonce alapján (minden újrapróbálkozásnak új van) eseményazonosító helyett.
Öt percnél többet eltérő óra.
Lassú munka végzése a válasz előtt, ami 15 másodpercnél időtúllépéshez vezet, és ugyanaz az esemény újra megérkezik.