Webhooks

RolChat leverer hendelser til systemene dine som signerte HTTP POST-forespørsler. Denne siden beskriver plugin-webhooks; webhooks sendt av en Automatiserings-regel skiller seg i nye forsøk, ventetid og rotasjon av hemmeligheten, se Automatiseringswebhooks. De samme reglene gjelder i motsatt retning når systemet ditt, en plugin eller en leverandør sender til RolChat. Verifiser hver leveranse i rekkefølgen nedenfor før du handler på den.

Slik ser en leveranse ut

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 utsending. En del av den signerte meldingen.
`X-RolChat-Signature`	`sha256=<hex>`. Prefikset angir algoritmen, slik at den kan endres senere.
`X-RolChat-Nonce`	En ULID som er unik for denne HTTP-forespørselen. Et nytt forsøk får en ny nonce.
`X-RolChat-Event-Id`	Hendelsens egen ID. Stabil på tvers av nye forsøk; bruk den til å fjerne duplikater.

Utgående leveranser går bare til HTTPS-endepunkter. En HTTP-URL avvises når abonnementet opprettes.

Signaturen

Den signerte meldingen er tidsstempelet, et punktum og den rå forespørselsbodyen, byte for byte:

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

Signer bytene du mottok, ikke en ny serialisering av den tolkede JSON-en. Endringer i mellomrom eller nøkkelrekkefølge ødelegger signaturen. SHA-256 er den eneste godtatte algoritmen.

Forespørsler som sendes av HTTP-handlingen i modulen Automatisering, signeres med to headere. X-RolChat-Signature er sha256= pluss HMAC-SHA256 av bare bodyen. X-RolChat-Signature-V2 er HMAC-SHA256 av <timestamp>.<body>, altså skjemaet beskrevet ovenfor, med X-RolChat-Timestamp som tidsstempel. Verifiser V2-headeren; headeren som bare dekker bodyen, beskytter ikke mot en gjenspilt forespørsel. Disse forespørslene har ingen X-RolChat-Nonce og ingen X-RolChat-Event-Id; hvert forsøk på én leveranse har samme X-RolChat-Delivery-Id og sitt eget nummer i X-RolChat-Attempt, så hopp over nonce-kontrollen og dedupliser på X-RolChat-Delivery-Id. Verifiseringseksemplene leser X-RolChat-Signature: for automatiseringsforespørsler leser du X-RolChat-Signature-V2 i stedet.

Verifisere en levering

Gjør disse fem kontrollene i rekkefølge. Eksempler i Python, Node.js, Go, Ruby og PHP finner du på siden Verifiseringseksempler.

Ferskhet. Avvis hvis |now − X-RolChat-Timestamp| > 300 sekunder (400). Fem minutter tåler klokkeavvik og gjør en oppfanget forespørsel verdiløs etter det. Hold serveren din synkronisert med NTP.
Signatur. Beregn den forventede verdien og sammenlign med en sammenligning i konstant tid (hmac.compare_digest, crypto.timingSafeEqual, hash_equals). Avvis med 401 ved avvik. En vanlig strengsammenligning lekker tidsinformasjon og er ikke akseptabel.
Nonce. Lagre X-RolChat-Nonce med en TTL på 10 minutter ved hjelp av en atomisk set-if-absent (SET NX EX 600). Hvis den allerede finnes, avviser du med 409: forespørselen er en gjentakelse. Hvis nonce-lageret ditt er nede, feiler du lukket med 503, slik at RolChat prøver igjen; fall aldri gjennom til «godta».
Tolk bodyen først nå.
Fjern duplikater etter hendelses-ID. Nye forsøk har en ny nonce, men samme X-RolChat-Event-Id. Hvis du har behandlet den ID-en de siste sju dagene, svarer du 200 uten å behandle den på nytt.

Svar 2xx så snart leveransen er trygt mottatt; gjør arbeidet asynkront. RolChat venter 15 sekunder på svar.

Hemmeligheter

En webhook-hemmelighet er 64 tilfeldige byte, base64url-kodet (omtrent 86 tegn). Den genereres når abonnementet eller pluginen opprettes, og vises én gang.
Lagre den i ditt eget hvelv eller miljø; RolChat beholder bare en kryptert kopi.
Rotasjon anbefales etter 90 dager; produktet viser en påminnelse, men deaktiverer aldri et abonnement fordi det ikke er rotert.
Rotasjon bruker et overlappingsvindu: etter POST /api/v1/plugins/{id}/webhook-secret/rotate verifiserer både den gamle og den nye hemmeligheten i sju dager, nye leveranser signeres med den nye, og den gamle slettes etter vinduet. Ingenting slutter å virke i det øyeblikket du roterer.
Hvis en hemmelighet lekker, gjør POST /api/v1/plugins/{id}/webhook-secret/revoke den ugyldig umiddelbart, utsteder en ny, sender e-post til kontoens administratorer og skriver en oppføring i revisjonsloggen.

Nye forsøk og døde meldinger

Et svar som ikke er 2xx, eller en nettverksfeil planlegger et nytt forsøk:

Forsøk	Forsinkelse etter det forrige
1	umiddelbart
2	15 sekunder
3	1 minutt
4	5 minutter
5	30 minutter
6	2 timer
7	8 timer
8	24 timer

408, 429, 5xx og nettverksfeil prøves på nytt. 400, 401, 403, 404 og 410 gjør ikke det: leveransen går rett til dead-letter-køen, fordi et nytt forsøk ikke kan hjelpe mot en avvist signatur eller et manglende endepunkt. Etter åtte mislykkede forsøk havner leveransen også i dead-letter-køen.

Døde meldinger oppbevares i 30 dager og er synlige i Innstillinger → Plugins → {plugin} → Webhook-logg → DLQ, der en administrator kan spille av en på nytt (POST /api/v1/plugins/{id}/webhook-dlq/{entry_id}/replay).

Grenser

Utgående body: 1 MB som standard (kan konfigureres per plugin). Innkommende body til RolChat: 5 MB. Større gir 413.
En plugin kan angi allowed_source_ips; RolChat bruker den tillatelseslisten før verifiseringen.
Du kan sjekke brukeragenten RolChat-Webhook/1.0 som en ekstra fornuftskontroll. Det er ikke et sikkerhetstiltak.

Innkommende webhooks til RolChat

Leverandører sender til RolChat på /api/v1/webhooks/{category}/{adapter} med sine egne signaturordninger (Twilio, Telnyx, Bandwidth, Meta for WhatsApp, Stripe). Hver adapter verifiserer leverandørens signatur, normaliserer nyttelasten og publiserer den på nytt på den interne hendelsesbussen med en RolChat-signatur. Ditt eget system kan sende til RolChat med de samme X-RolChat-*-headerne som er beskrevet ovenfor, signert med hemmeligheten til pluginen som eier endepunktet.

Automatiseringswebhooks

Handlingen Send HTTP-forespørsel i modulen Automatisering har egne leveringsregler:

Én hemmelighet per konto. Vis eller roter den på skjermbildet Automatisering (eier og administrator). Rotasjonen gjelder umiddelbart: det finnes ikke noe overlappingsvindu, den gamle hemmeligheten slutter å verifiseres med en gang, så oppdater mottakeren først eller godta et kort opphold.
Ventetid: RolChat venter 10 sekunder på et svar.
Nye forsøk: opptil 6 forsøk til sammen. Pausen før forsøk 2 er 30 sekunder, deretter omtrent 2 minutter, 8 minutter, 32 minutter og 2 timer 8 minutter, hver variert med opptil 20 %. En enkelt pause overstiger aldri 6 timer.
Hva som prøves på nytt: nettverksfeil, tidsavbrudd, 5xx, 408, 425 og 429. Andre 4xx-svar, en blokkert adresse eller en for stor body prøves ikke på nytt: leveransen går rett til dead-letter-køen, slik den gjør etter det siste mislykkede forsøket.
Headere: X-RolChat-Signature, X-RolChat-Signature-V2, X-RolChat-Timestamp, X-RolChat-Delivery-Id, X-RolChat-Attempt.

Teste mottakeren din

POST /api/v1/webhooks/test-signature sender en syntetisk signert hendelse til endepunktet til pluginen som kaller, slik at du kan verifisere implementasjonen fra ende til ende før ekte trafikk kommer.

Vanlige feil

Å verifisere mot den tolkede og omkodede JSON-en i stedet for de rå bytene.
Å bruke == til å sammenligne signaturer.
Å fjerne duplikater etter nonce (hvert nytt forsøk har en ny) i stedet for etter hendelses-ID.
En klokke som går mer enn fem minutter feil.
Å gjøre tregt arbeid før du svarer, og deretter få tidsavbrudd etter 15 sekunder og motta den samme hendelsen igjen.