Webhooks

RolChat leverer hændelser til dine systemer som signerede HTTP POST-anmodninger. Denne side beskriver plugin-webhooks; webhooks sendt af en Automatiserings-regel adskiller sig i genforsøg, ventetid og rotation af hemmeligheden, se Automatiseringswebhooks. De samme regler gælder i den anden retning, når dit system, et plugin eller en udbyder sender til RolChat. Verificér hver levering i rækkefølgen nedenfor, før du handler på den.

Sådan ser en levering ud

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

Header	Betydning
`X-RolChat-Timestamp`	Unix-sekunder ved afsendelsen. En del af den signerede besked.
`X-RolChat-Signature`	`sha256=<hex>`. Præfikset navngiver algoritmen, så den kan ændres senere.
`X-RolChat-Nonce`	En ULID, der er unik for denne HTTP-anmodning. Et genforsøg får en ny nonce.
`X-RolChat-Event-Id`	Hændelsens eget id. Stabilt på tværs af genforsøg; brug det til deduplikering.

Udgående leveringer går kun til HTTPS-endpoints. En HTTP-URL afvises, når abonnementet oprettes.

Signaturen

Den signerede besked er tidsstemplet, et bogstaveligt punktum og den rå anmodningsbody, byte for byte:

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

Signér de bytes, du modtog, ikke en genserialiseret kopi af den parsede JSON. Ændringer i mellemrum eller nøglernes rækkefølge ødelægger signaturen. SHA-256 er den eneste accepterede algoritme.

Anmodninger, der sendes af HTTP-handlingen i modulet Automatisering, signeres med to headere. X-RolChat-Signature er sha256= plus HMAC-SHA256 af kun body. X-RolChat-Signature-V2 er HMAC-SHA256 af <timestamp>.<body>, altså skemaet beskrevet ovenfor, med X-RolChat-Timestamp som tidsstempel. Verificér V2-headeren; headeren med kun body beskytter ikke mod en genafspillet anmodning. Disse anmodninger har hverken X-RolChat-Nonce eller X-RolChat-Event-Id; hvert forsøg på én levering har samme X-RolChat-Delivery-Id og sit eget nummer i X-RolChat-Attempt, så spring kontrollen af nonce over og deduplikér efter X-RolChat-Delivery-Id. Verifikationseksemplerne læser X-RolChat-Signature: for automatiseringsanmodninger skal du i stedet læse X-RolChat-Signature-V2.

Verifikation af en levering

Udfør disse fem kontroller i rækkefølge. Eksempler i Python, Node.js, Go, Ruby og PHP findes på siden Verifikationseksempler.

Aktualitet. Afvis, hvis |now − X-RolChat-Timestamp| > 300 sekunder (400). Fem minutter tolererer forskelle i urene og gør en opsnappet anmodning værdiløs derefter. Hold din server synkroniseret med NTP.
Signatur. Beregn den forventede værdi, og sammenlign med en sammenligning i konstant tid (hmac.compare_digest, crypto.timingSafeEqual, hash_equals). Afvis med 401 ved uoverensstemmelse. En almindelig strengsammenligning lækker timinginformation og er ikke acceptabel.
Nonce. Gem X-RolChat-Nonce med en TTL på 10 minutter ved hjælp af en atomisk set-if-absent (SET NX EX 600). Findes den allerede, afvis med 409: anmodningen er en genafspilning. Er dit noncelager nede, så fejl lukket med 503, så RolChat prøver igen; fald aldrig igennem til “accepter”.
Parse først body nu.
Dedupliker efter hændelses-id. Genforsøg har en ny nonce, men den samme X-RolChat-Event-Id. Har du behandlet det id inden for de seneste syv dage, så svar 200 uden at behandle det igen.

Svar 2xx, så snart leveringen er sikkert modtaget; udfør arbejdet asynkront. RolChat venter 15 sekunder på et svar.

Hemmeligheder

En webhookhemmelighed er 64 tilfældige bytes, base64url-kodet (cirka 86 tegn). Den genereres, når abonnementet eller pluginet oprettes, og vises én gang.
Gem den i din egen boks eller dit eget miljø; RolChat beholder kun en krypteret kopi.
Rotation anbefales efter 90 dage; produktet viser en påmindelse, men deaktiverer aldrig et abonnement, fordi det ikke er roteret.
Rotation bruger et overlapningsvindue: efter POST /api/v1/plugins/{id}/webhook-secret/rotate verificerer både den gamle og den nye hemmelighed i syv dage, nye leveringer signeres med den nye, og den gamle slettes efter vinduet. Intet går i stykker i det øjeblik, du roterer.
Lækker en hemmelighed, gør POST /api/v1/plugins/{id}/webhook-secret/revoke den ugyldig med det samme, udsteder en ny, sender en e-mail til kontoens administratorer og skriver en post i revisionsloggen.

Genforsøg og døde beskeder

Et svar, der ikke er 2xx, eller en netværksfejl planlægger et genforsøg:

Forsøg	Forsinkelse efter det forrige
1	med det samme
2	15 sekunder
3	1 minut
4	5 minutter
5	30 minutter
6	2 timer
7	8 timer
8	24 timer

408, 429, 5xx og netværksfejl forsøges igen. 400, 401, 403, 404 og 410 gør ikke: leveringen går direkte til køen for døde beskeder, fordi et genforsøg ikke kan hjælpe på en afvist signatur eller et manglende endpoint. Efter otte mislykkede forsøg ender leveringen også i køen for døde beskeder.

Døde beskeder gemmes i 30 dage og er synlige under Indstillinger → Plugins → {plugin} → Webhooklog → DLQ, hvor en administrator kan afspille en igen (POST /api/v1/plugins/{id}/webhook-dlq/{entry_id}/replay).

Grænser

Udgående body: 1 MB som standard (kan konfigureres pr. plugin). Indgående body til RolChat: 5 MB. Større giver 413.
Et plugin kan angive allowed_source_ips; RolChat anvender den tilladelsesliste før verifikationen.
Du kan fastlåse user agenten RolChat-Webhook/1.0 som en ekstra fornuftskontrol. Det er ikke en sikkerhedsforanstaltning.

Indgående webhooks til RolChat

Udbydere sender til RolChat på /api/v1/webhooks/{category}/{adapter} med deres egne signaturmetoder (Twilio, Telnyx, Bandwidth, Meta for WhatsApp, Stripe). Hver adapter verificerer sin udbyders signatur, normaliserer indholdet og genudgiver det på den interne hændelsesbus med en RolChat-signatur. Dit eget system kan sende til RolChat med de samme X-RolChat-*-headere som beskrevet ovenfor, signeret med hemmeligheden fra det plugin, der ejer endpointet.

Automatiseringswebhooks

Handlingen Send HTTP-anmodning i modulet Automatisering har egne leveringsregler:

Én hemmelighed pr. konto. Vis eller roter den på skærmbilledet Automatisering (ejer og administrator). Rotationen virker med det samme: der er intet overlapsvindue, den gamle hemmelighed verificeres straks ikke mere, så opdatér først din modtager eller accepter et kort hul.
Ventetid: RolChat venter 10 sekunder på et svar.
Genforsøg: op til 6 forsøg i alt. Pausen før forsøg 2 er 30 sekunder, derefter cirka 2 minutter, 8 minutter, 32 minutter og 2 timer 8 minutter, hver varieret med op til 20 %. En enkelt pause overstiger aldrig 6 timer.
Hvad der forsøges igen: netværksfejl, timeouts, 5xx, 408, 425 og 429. Andre 4xx-svar, en blokeret adresse eller en for stor body forsøges ikke igen: leveringen går direkte til køen for døde beskeder, ligesom efter det sidste mislykkede forsøg.
Headere: X-RolChat-Signature, X-RolChat-Signature-V2, X-RolChat-Timestamp, X-RolChat-Delivery-Id, X-RolChat-Attempt.

Test af din modtager

POST /api/v1/webhooks/test-signature sender en syntetisk signeret hændelse til endpointet for det kaldende plugin, så du kan verificere din implementering fra ende til anden, før rigtig trafik ankommer.

Almindelige fejl

At verificere mod den parsede og genkodede JSON i stedet for de rå bytes.
At bruge == til at sammenligne signaturer.
At deduplikere efter nonce (hvert genforsøg har en ny) i stedet for efter hændelses-id.
Et ur, der går mere end fem minutter forkert.
At udføre langsomt arbejde, før der svares, og så løbe ud i timeout efter 15 sekunder og modtage den samme hændelse igen.