Webhooks

RolChat levert gebeurtenissen aan je systemen als ondertekende HTTP-POST-verzoeken. Deze pagina beschrijft plug-in-webhooks; webhooks die een Automatisering-regel verstuurt, verschillen in nieuwe pogingen, wachttijd en rotatie van het geheim, zie Automatiseringswebhooks. Dezelfde regels gelden in de andere richting, wanneer je eigen systeem, een plug-in of een provider iets naar RolChat stuurt. Verifieer elke levering in de onderstaande volgorde voordat je er iets mee doet.

Hoe een levering eruitziet

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	Betekenis
X-RolChat-Timestamp	Unix-seconden op het moment van verzenden. Onderdeel van het ondertekende bericht.
X-RolChat-Signature	sha256=<hex>. Het voorvoegsel noemt het algoritme, zodat dat later kan veranderen.
X-RolChat-Nonce	Een ULID die uniek is voor dit HTTP-verzoek. Een nieuwe poging krijgt een nieuwe nonce.
X-RolChat-Event-Id	De eigen ID van de gebeurtenis. Blijft gelijk bij nieuwe pogingen; gebruik hem om te ontdubbelen.

Uitgaande leveringen gaan alleen naar HTTPS-endpoints. Een HTTP-URL wordt geweigerd bij het aanmaken van het abonnement.

De handtekening

Het ondertekende bericht bestaat uit het tijdstempel, een letterlijke punt en de ruwe requestbody, byte voor byte:

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

Onderteken de bytes die je hebt ontvangen, niet een opnieuw geserialiseerde kopie van de geparste JSON. Wijzigingen in witruimte of in de volgorde van sleutels breken de handtekening. SHA-256 is het enige geaccepteerde algoritme.

Automatiseringsactie ‘HTTP-verzoek verzenden’

Verzoeken die de HTTP-actie van de module Automatisering verstuurt, worden met twee headers ondertekend. X-RolChat-Signature is sha256= plus de HMAC-SHA256 van alleen de body. X-RolChat-Signature-V2 is de HMAC-SHA256 van <timestamp>.<body>, het hierboven beschreven schema, met X-RolChat-Timestamp als tijdstempel. Verifieer de V2-header; de header die alleen de body dekt, beschermt niet tegen een opnieuw afgespeeld verzoek. Deze verzoeken bevatten geen X-RolChat-Nonce en geen X-RolChat-Event-Id; elke poging van één levering bevat dezelfde X-RolChat-Delivery-Id en een eigen nummer in X-RolChat-Attempt, dus sla de nonce-controle over en ontdubbel op X-RolChat-Delivery-Id. De verificatievoorbeelden lezen X-RolChat-Signature: lees voor automatiseringsverzoeken in plaats daarvan X-RolChat-Signature-V2.

Een levering controleren

Voer deze vijf controles in deze volgorde uit. Voorbeelden in Python, Node.js, Go, Ruby en PHP staan op de pagina Verificatievoorbeelden.

1. Versheid. Weiger als |now − X-RolChat-Timestamp| > 300 seconden (400). Vijf minuten vangt klokafwijkingen op en maakt een onderschept verzoek daarna waardeloos. Houd je server gesynchroniseerd via NTP.
2. Handtekening. Bereken de verwachte waarde en vergelijk met een vergelijking in constante tijd (hmac.compare_digest, crypto.timingSafeEqual, hash_equals). Weiger met 401 bij een afwijking. Een gewone stringvergelijking lekt timinginformatie en is niet acceptabel.
3. Nonce. Sla X-RolChat-Nonce op met een TTL van 10 minuten via een atomaire set-if-absent (SET NX EX 600). Bestaat hij al, weiger dan met 409: het verzoek is een replay. Ligt je noncestore eruit, faal dan gesloten met 503, zodat RolChat het opnieuw probeert; val nooit terug op “accepteren”.
4. Parse de body pas nu.
5. Ontdubbel op gebeurtenis-ID. Nieuwe pogingen hebben een nieuwe nonce, maar dezelfde X-RolChat-Event-Id. Heb je die ID in de afgelopen zeven dagen al verwerkt, antwoord dan 200 zonder opnieuw te verwerken.

Antwoord 2xx zodra de levering veilig is aangenomen; doe het werk asynchroon. RolChat wacht 15 seconden op een antwoord.

Geheimen

• Een webhookgeheim bestaat uit 64 willekeurige bytes, base64url-gecodeerd (ongeveer 86 tekens). Het wordt gegenereerd bij het aanmaken van het abonnement of de plug-in en één keer getoond.
• Bewaar het in je eigen kluis of omgeving; RolChat bewaart alleen een versleutelde kopie.
• Rotatie wordt na 90 dagen aanbevolen; het product toont een herinnering, maar schakelt een abonnement nooit uit omdat er niet is geroteerd.
• Rotatie gebruikt een overlapvenster: na POST /api/v1/plugins/{id}/webhook-secret/rotate worden zowel het oude als het nieuwe geheim zeven dagen lang geaccepteerd, nieuwe leveringen worden met het nieuwe ondertekend en het oude wordt na het venster verwijderd. Op het moment van roteren gaat er niets stuk.
• Lekt een geheim uit, dan maakt POST /api/v1/plugins/{id}/webhook-secret/revoke het direct ongeldig, geeft een nieuw uit, mailt de beheerders van het account en schrijft een auditregel.

Nieuwe pogingen en dead letters

Een andere response dan 2xx of een netwerkfout plant een nieuwe poging in:

Poging	Wachttijd na de vorige
1	direct
2	15 seconden
3	1 minuut
4	5 minuten
5	30 minuten
6	2 uur
7	8 uur
8	24 uur

408, 429, 5xx en netwerkfouten worden opnieuw geprobeerd. 400, 401, 403, 404 en 410 niet: de levering gaat direct naar de dead-letter-wachtrij, omdat opnieuw proberen niet helpt bij een geweigerde handtekening of een ontbrekend endpoint. Na acht mislukte pogingen gaat de levering ook naar de dead-letter-wachtrij.

Dead letters worden 30 dagen bewaard en zijn zichtbaar in Instellingen → Plug-ins → {plug-in} → Webhooklogboek → DLQ, waar een beheerder er een opnieuw kan afspelen (POST /api/v1/plugins/{id}/webhook-dlq/{entry_id}/replay).

Limieten

• Uitgaande body: standaard 1 MB (per plug-in in te stellen). Inkomende body naar RolChat: 5 MB. Groter geeft 413.
• Een plug-in kan allowed_source_ips opgeven; RolChat past die toelatingslijst toe vóór het verifiëren.
• Je kunt als extra controle op de user agent RolChat-Webhook/1.0 filteren. Dat is geen beveiligingsmaatregel.

Inkomende webhooks naar RolChat

Providers sturen naar RolChat op /api/v1/webhooks/{category}/{adapter} met hun eigen handtekeningschema’s (Twilio, Telnyx, Bandwidth, Meta voor WhatsApp, Stripe). Elke adapter verifieert de handtekening van zijn provider, normaliseert de payload en publiceert die opnieuw op de interne eventbus met een RolChat-handtekening. Je eigen systeem kan naar RolChat sturen met dezelfde hierboven beschreven X-RolChat-*-headers, ondertekend met het geheim van de plug-in die eigenaar is van het endpoint.

Automatiseringswebhooks

De actie HTTP-verzoek versturen van de module Automatisering heeft eigen leveringsregels:

• Eén geheim per account. Bekijk of roteer het op het scherm Automatisering (Eigenaar en Beheerder). Rotatie werkt direct: er is geen overlapperiode, het oude geheim wordt meteen niet meer geverifieerd, dus werk eerst je ontvanger bij of accepteer een korte onderbreking.
• Wachttijd: RolChat wacht 10 seconden op een antwoord.
• Nieuwe pogingen: maximaal 6 pogingen in totaal. De pauze voor poging 2 is 30 seconden, daarna ongeveer 2 minuten, 8 minuten, 32 minuten en 2 uur 8 minuten, elk met een variatie van maximaal 20 %. Een enkele pauze duurt nooit langer dan 6 uur.
• Wat opnieuw wordt geprobeerd: netwerkfouten, time-outs, 5xx, 408, 425 en 429. Andere 4xx-antwoorden, een geblokkeerd adres of een te grote body worden niet opnieuw geprobeerd: de levering gaat direct naar de dead-letter-wachtrij, net als na de laatste mislukte poging.
• Headers: X-RolChat-Signature, X-RolChat-Signature-V2, X-RolChat-Timestamp, X-RolChat-Delivery-Id, X-RolChat-Attempt.

Je ontvanger testen

POST /api/v1/webhooks/test-signature stuurt een synthetische ondertekende gebeurtenis naar het endpoint van de aanroepende plug-in, zodat je je implementatie van begin tot eind kunt verifiëren voordat er echt verkeer binnenkomt.

Veelgemaakte fouten

• Verifiëren tegen de geparste en opnieuw gecodeerde JSON in plaats van de ruwe bytes.
• == gebruiken om handtekeningen te vergelijken.
• Ontdubbelen op nonce (elke nieuwe poging heeft een nieuwe) in plaats van op gebeurtenis-ID.
• Een klok die meer dan vijf minuten afwijkt.
• Traag werk doen vóór het antwoorden, dan na 15 seconden een time-out krijgen en dezelfde gebeurtenis opnieuw ontvangen.