Webhooks

RolChat levererar händelser till dina system som signerade HTTP-förfrågningar av typen POST. Den här sidan beskriver plugin-webhooks; webhooks som skickas av en Automatisering-regel skiljer sig i omförsök, väntetid och rotation av hemligheten, se Automationswebhooks. Samma regler gäller i den andra riktningen när ditt system, ett plugin eller en leverantör skickar till RolChat. Verifiera varje leverans i ordningen nedan innan du agerar på den.

Hur en leverans ser 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	Betydelse
X-RolChat-Timestamp	Unix-sekunder vid utskicket. Ingår i det signerade meddelandet.
X-RolChat-Signature	sha256=<hex>. Prefixet anger algoritmen så att den kan ändras senare.
X-RolChat-Nonce	Ett ULID som är unikt för den här HTTP-förfrågan. Ett nytt försök får en ny nonce.
X-RolChat-Event-Id	Händelsens eget ID. Stabilt mellan nya försök; använd det för att ta bort dubbletter.

Utgående leveranser går bara till HTTPS-endpoints. En HTTP-URL avvisas när prenumerationen skapas.

Signaturen

Det signerade meddelandet är tidsstämpeln, en bokstavlig punkt och den råa bodyn i förfrågan, byte för byte:

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

Signera de byte du tog emot, inte en omserialiserad kopia av den tolkade JSON:en. Ändringar i blanksteg eller nyckelordning förstör signaturen. SHA-256 är den enda accepterade algoritmen.

Automationsåtgärden “Skicka HTTP-förfrågan”

Förfrågningar som skickas av HTTP-åtgärden i modulen Automation signeras med två headers. X-RolChat-Signature är sha256= plus HMAC-SHA256 av enbart bodyn. X-RolChat-Signature-V2 är HMAC-SHA256 av <timestamp>.<body>, schemat som beskrivs ovan, med X-RolChat-Timestamp som tidsstämpel. Verifiera V2-headern; headern med enbart body skyddar inte mot en återuppspelad förfrågan. Dessa förfrågningar har varken X-RolChat-Nonce eller X-RolChat-Event-Id; varje försök av en leverans har samma X-RolChat-Delivery-Id och ett eget nummer i X-RolChat-Attempt, så hoppa över nonce-kontrollen och deduplicera på X-RolChat-Delivery-Id. Verifieringsexemplen läser X-RolChat-Signature: för automationsförfrågningar läser du i stället X-RolChat-Signature-V2.

Verifiera en leverans

Gör de här fem kontrollerna i ordning. Exempel i Python, Node.js, Go, Ruby och PHP finns på sidan verifieringsexempel.

1. Aktualitet. Avvisa om |now − X-RolChat-Timestamp| > 300 sekunder (400). Fem minuter tolererar klockavvikelser och gör en uppsnappad förfrågan värdelös därefter. Håll din server synkad med NTP.
2. Signatur. Beräkna det förväntade värdet och jämför med en jämförelse i konstant tid (hmac.compare_digest, crypto.timingSafeEqual, hash_equals). Avvisa med 401 vid avvikelse. En vanlig strängjämförelse läcker tidsinformation och är inte godtagbar.
3. Nonce. Spara X-RolChat-Nonce med en TTL på 10 minuter med en atomisk operation som bara sätter värdet om det saknas (SET NX EX 600). Om den redan finns avvisar du med 409: förfrågan är en återuppspelning. Om ditt nonce-lager är nere, misslyckas säkert med 503 så att RolChat försöker igen; fall aldrig igenom till “acceptera”.
4. Tolka bodyn först nu.
5. Ta bort dubbletter utifrån händelse-ID. Nya försök har en ny nonce men samma X-RolChat-Event-Id. Om du har bearbetat det ID:t under de senaste sju dagarna svarar du 200 utan att bearbeta igen.

Svara 2xx så snart leveransen har tagits emot på ett säkert sätt; gör arbetet asynkront. RolChat väntar 15 sekunder på ett svar.

Hemligheter

• En webhook-hemlighet är 64 slumpmässiga byte, kodade i base64url (cirka 86 tecken). Den genereras när prenumerationen eller pluginet skapas och visas en gång.
• Förvara den i ditt eget valv eller din egen miljö; RolChat sparar bara en krypterad kopia.
• Rotation rekommenderas efter 90 dagar; produkten visar en påminnelse men inaktiverar aldrig en prenumeration för att den inte har roterats.
• Rotationen använder ett överlappsfönster: efter POST /api/v1/plugins/{id}/webhook-secret/rotate verifierar både den gamla och den nya hemligheten i sju dagar, nya leveranser signeras med den nya och den gamla raderas efter fönstret. Inget går sönder i samma stund som du roterar.
• Om en hemlighet läcker gör POST /api/v1/plugins/{id}/webhook-secret/revoke den ogiltig omedelbart, utfärdar en ny, mejlar kontots administratörer och skriver en post i granskningsloggen.

Nya försök och döda meddelanden

Ett svar som inte är 2xx eller ett nätverksfel schemalägger ett nytt försök:

Försök	Fördröjning efter föregående
1	omedelbart
2	15 sekunder
3	1 minut
4	5 minuter
5	30 minuter
6	2 timmar
7	8 timmar
8	24 timmar

408, 429, 5xx och nätverksfel görs om. 400, 401, 403, 404 och 410 görs inte om: leveransen går direkt till kön för döda meddelanden, eftersom ett nytt försök inte kan hjälpa mot en avvisad signatur eller en saknad endpoint. Efter åtta misslyckade försök hamnar leveransen också bland de döda meddelandena.

Döda meddelanden sparas i 30 dagar och syns under Inställningar → Plugins → {plugin} → Webhook-logg → DLQ, där en administratör kan spela upp ett igen (POST /api/v1/plugins/{id}/webhook-dlq/{entry_id}/replay).

Gränser

• Utgående body: 1 MB som standard (konfigurerbart per plugin). Inkommande body till RolChat: 5 MB. Större ger 413.
• Ett plugin kan ange allowed_source_ips; RolChat tillämpar den tillåtelselistan före verifieringen.
• Du kan kontrollera användaragenten RolChat-Webhook/1.0 som en extra rimlighetskontroll. Det är ingen säkerhetskontroll.

Inkommande webhooks till RolChat

Leverantörer skickar till RolChat på /api/v1/webhooks/{category}/{adapter} med sina egna signaturmetoder (Twilio, Telnyx, Bandwidth, Meta för WhatsApp, Stripe). Varje adapter verifierar sin leverantörs signatur, normaliserar nyttolasten och publicerar den på nytt på den interna händelsebussen med en RolChat-signatur. Ditt eget system kan skicka till RolChat med samma headers X-RolChat-* som beskrivs ovan, signerade med hemligheten för det plugin som äger endpointen.

Automationswebhooks

Åtgärden Skicka HTTP-förfrågan i modulen Automation har egna leveransregler:

• En hemlighet per konto. Visa eller rotera den på skärmen Automation (ägare och administratör). Rotationen gäller direkt: det finns inget överlappningsfönster, den gamla hemligheten slutar verifieras omedelbart, så uppdatera först din mottagare eller acceptera ett kort glapp.
• Väntetid: RolChat väntar 10 sekunder på ett svar.
• Omförsök: upp till 6 försök totalt. Pausen före försök 2 är 30 sekunder, därefter cirka 2 minuter, 8 minuter, 32 minuter och 2 timmar 8 minuter, var och en varierad med upp till 20 %. En enskild paus överstiger aldrig 6 timmar.
• Vad som görs om: nätverksfel, tidsgränser, 5xx, 408, 425 och 429. Andra 4xx-svar, en blockerad adress eller en för stor body görs inte om: leveransen går direkt till kön för döda meddelanden, liksom efter det sista misslyckade försöket.
• Headers: X-RolChat-Signature, X-RolChat-Signature-V2, X-RolChat-Timestamp, X-RolChat-Delivery-Id, X-RolChat-Attempt.

Testa din mottagare

POST /api/v1/webhooks/test-signature skickar en syntetisk signerad händelse till det anropande pluginets endpoint så att du kan verifiera din implementation från början till slut innan den riktiga trafiken kommer.

Vanliga misstag

• Att verifiera mot den tolkade och omkodade JSON:en i stället för de råa byten.
• Att använda == för att jämföra signaturer.
• Att ta bort dubbletter utifrån nonce (varje nytt försök har en ny) i stället för utifrån händelse-ID.
• En klocka som går mer än fem minuter fel.
• Att göra långsamt arbete innan du svarar, sedan överskrida tidsgränsen på 15 sekunder och få samma händelse igen.