Webhooks

RolChat lewer gebeurtenisse aan jou stelsels af as ondertekende HTTP POST-versoeke. Hierdie bladsy beskryf inprop-webhooks; webhooks wat deur ’n Outomatisering-reël gestuur word, verskil in herprobasies, wagtyd en geheimrotasie, sien Outomatisering-webhooks. Dieselfde reëls geld in die ander rigting wanneer jou stelsel, ’n inprop of ’n verskaffer na RolChat stuur. Verifieer elke aflewering in die volgorde hieronder voordat jy daarop optree.

Hoe ’n aflewering lyk

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

Opskrif	Betekenis
`X-RolChat-Timestamp`	Unix-sekondes by versending. Deel van die ondertekende boodskap.
`X-RolChat-Signature`	`sha256=<hex>`. Die voorvoegsel noem die algoritme sodat dit later kan verander.
`X-RolChat-Nonce`	’n ULID uniek aan hierdie HTTP-versoek. ’n Herprobeer kry ’n nuwe nonce.
`X-RolChat-Event-Id`	Die gebeurtenis se eie ID. Stabiel oor herprobasies heen; gebruik dit om te ontdubbel.

Uitgaande aflewerings gaan slegs na HTTPS-eindpunte. ’n HTTP-URL word verwerp wanneer die intekening geskep word.

Die handtekening

Die ondertekende boodskap is die tydstempel, ’n letterlike punt, en die rou versoekliggaam, greep vir greep:

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

Onderteken die grepe wat jy ontvang het, nie ’n herserialiseerde kopie van die ontlede JSON nie. Veranderinge in witspasie of sleutelvolgorde breek die handtekening. SHA-256 is die enigste aanvaarde algoritme.

Versoeke wat deur die HTTP-aksie van die Outomatisering-module gestuur word, word met twee opskrifte onderteken. X-RolChat-Signature is sha256= plus die HMAC-SHA256 van slegs die liggaam. X-RolChat-Signature-V2 is die HMAC-SHA256 van <timestamp>.<body>, die skema wat hierbo beskryf is, met X-RolChat-Timestamp as die tydstempel. Verifieer die V2-opskrif; die opskrif met slegs die liggaam beskerm nie teen ’n herspeelde versoek nie. Hierdie versoeke dra nie X-RolChat-Nonce of X-RolChat-Event-Id nie; elke poging van een aflewering dra dieselfde X-RolChat-Delivery-Id en sy eie nommer in X-RolChat-Attempt, so slaan die nonce-kontrole oor en ontdubbel volgens X-RolChat-Delivery-Id. Die verifikasievoorbeelde lees X-RolChat-Signature: lees vir outomatiseringsversoeke eerder X-RolChat-Signature-V2.

Verifieer ’n aflewering

Doen hierdie vyf kontroles in volgorde. Voorbeelde in Python, Node.js, Go, Ruby en PHP is op die bladsy verifikasievoorbeelde.

Varsheid. Verwerp as |now − X-RolChat-Timestamp| > 300 sekondes (400). Vyf minute verdra klokskeefheid en maak ’n onderskepte versoek daarna waardeloos. Hou jou bediener op NTP.
Handtekening. Bereken die verwagte waarde en vergelyk met ’n konstante-tyd-vergelyking (hmac.compare_digest, crypto.timingSafeEqual, hash_equals). Verwerp met 401 by ’n wanpassing. ’n Gewone stringvergelyking lek tydsinligting en is nie aanvaarbaar nie.
Nonce. Stoor X-RolChat-Nonce met ’n TTL van 10 minute deur ’n atomiese stel-indien-afwesig (SET NX EX 600). As dit reeds bestaan, verwerp met 409: die versoek is ’n herspeling. As jou nonce-stoor af is, misluk veilig met 503 sodat RolChat herprobeer; val nooit deur na “aanvaar” nie.
Ontleed die liggaam eers nou.
Ontdubbel volgens gebeurtenis-ID. Herprobasies dra ’n nuwe nonce maar dieselfde X-RolChat-Event-Id. As jy daardie ID in die afgelope sewe dae verwerk het, antwoord 200 sonder om dit weer te verwerk.

Antwoord 2xx sodra die aflewering veilig aanvaar is; doen die werk asinchronies. RolChat wag 15 sekondes vir ’n antwoord.

Geheime

’n Webhook-geheim is 64 ewekansige grepe, base64url-geënkodeer (sowat 86 karakters). Dit word gegenereer wanneer die intekening of inprop geskep word en word een keer gewys.
Stoor dit in jou eie kluis of omgewing; RolChat hou slegs ’n geïnkripteerde kopie.
Rotasie word ná 90 dae aanbeveel; die produk wys ’n herinnering maar deaktiveer nooit ’n intekening omdat dit nie geroteer is nie.
Rotasie gebruik ’n oorvleuelingsvenster: ná POST /api/v1/plugins/{id}/webhook-secret/rotate verifieer die ou en die nuwe geheim albei vir sewe dae, nuwe aflewerings word met die nuwe een onderteken, en die ou een word ná die venster geskrap. Niks breek op die oomblik dat jy roteer nie.
As ’n geheim uitlek, maak POST /api/v1/plugins/{id}/webhook-secret/revoke dit onmiddellik ongeldig, reik ’n nuwe een uit, e-pos die rekening se admins en skryf ’n ouditinskrywing.

Herprobasies en dooie briewe

’n Antwoord wat nie 2xx is nie, of ’n netwerkmislukking, skeduleer ’n herprobeer:

Poging	Vertraging ná die vorige een
1	onmiddellik
2	15 sekondes
3	1 minuut
4	5 minute
5	30 minute
6	2 uur
7	8 uur
8	24 uur

408, 429, 5xx en netwerkfoute word herprobeer. 400, 401, 403, 404 en 410 nie: die aflewering gaan reguit na die dooiebrieftou, want om ’n verwerpte handtekening of ’n ontbrekende eindpunt te herprobeer, kan nie help nie. Ná agt mislukte pogings word die aflewering ook ’n dooie brief.

Dooie briewe word vir 30 dae gehou en is sigbaar in Instellings → Inproppe → {inprop} → Webhook-log → DLQ, waar ’n admin een kan herspeel (POST /api/v1/plugins/{id}/webhook-dlq/{entry_id}/replay).

Limiete

Uitgaande liggaam: 1 MB by verstek (opstelbaar per inprop). Inkomende liggaam na RolChat: 5 MB. Groter is 413.
’n Inprop kan allowed_source_ips verklaar; RolChat pas daardie toelaatlys toe voordat dit verifieer.
Jy kan op die RolChat-Webhook/1.0-gebruikersagent vaspen as ’n ekstra gesonde-verstand-kontrole. Dit is nie ’n sekuriteitskontrole nie.

Inkomende webhooks na RolChat

Verskaffers stuur na RolChat by /api/v1/webhooks/{category}/{adapter} met hul eie handtekeningskemas (Twilio, Telnyx, Bandwidth, Meta vir WhatsApp, Stripe). Elke adapter verifieer sy verskaffer se handtekening, normaliseer die loonvrag en publiseer dit weer op die interne gebeurtenisbus met ’n RolChat-handtekening. Jou eie stelsel kan na RolChat stuur met dieselfde X-RolChat-*-opskrifte wat hierbo beskryf word, onderteken met die geheim van die inprop wat die eindpunt besit.

Outomatisering-webhooks

Die Stuur HTTP-versoek-aksie van die Outomatisering-module het sy eie afleweringsreëls:

Een geheim per rekening. Wys of roteer dit op die Outomatisering-skerm (Eienaar en Admin). Rotasie tree dadelik in werking: daar is geen oorvleuelingsvenster nie, die ou geheim hou dadelik op verifieer, so werk eers jou ontvanger by of aanvaar ’n kort gaping.
Wagtyd: RolChat wag 10 sekondes vir ’n antwoord.
Herprobasies: tot 6 pogings in totaal. Die pouse voor poging 2 is 30 sekondes, dan sowat 2 minute, 8 minute, 32 minute en 2 uur 8 minute, elk met tot 20 % variasie. ’n Enkele pouse oorskry nooit 6 uur nie.
Wat herprobeer word: netwerkfoute, uittellings, 5xx, 408, 425 en 429. Ander 4xx-antwoorde, ’n geblokkeerde adres of ’n te groot liggaam word nie herprobeer nie: die aflewering gaan reguit na die dooie-briewe-tou, soos ná die laaste mislukte poging.
Opskrifte: X-RolChat-Signature, X-RolChat-Signature-V2, X-RolChat-Timestamp, X-RolChat-Delivery-Id, X-RolChat-Attempt.

Toets jou ontvanger

POST /api/v1/webhooks/test-signature stuur ’n sintetiese ondertekende gebeurtenis na die eindpunt van die roepende inprop sodat jy jou implementering van punt tot punt kan verifieer voordat werklike verkeer aankom.

Algemene foute

Verifieer teen die ontlede en herkodeerde JSON in plaas van die rou grepe.
Gebruik == om handtekeninge te vergelyk.
Ontdubbel volgens nonce (elke herprobeer het ’n nuwe een) in plaas van volgens gebeurtenis-ID.
’n Klok wat meer as vyf minute af is.
Doen stadige werk voordat jy antwoord, en tel dan by 15 sekondes uit en ontvang dieselfde gebeurtenis weer.