Telm kan moderatie-events in realtime naar je server pushen. Je registreert een endpoint, kiest welke events je wilt ontvangen, en Telm stuurt voor elk een ondertekende POST. Elke levering draagt een HMAC-SHA256-handtekening die je verifieert met je endpoint-geheim. Mislukte leveringen worden volgens een schema opnieuw geprobeerd; een permanent onbereikbaar endpoint wordt automatisch uitgeschakeld.
1De event-envelop
Elke webhook is een HTTP POST met een JSON-body in een gemeenschappelijke envelop. De envelop heeft een id (een unieke leveringsidentificator voor ontdubbeling), een type (de eventnaam), een created_at-tijdstempel, de group_id waar het event bij hoort, en een data-object waarvan de vorm afhangt van het eventtype.
De id is deterministisch voor echte events, dus als hetzelfde event twee keer wordt geleverd — bijvoorbeeld na een retry — ontvang je beide keren dezelfde id. Gebruik de X-Telm-Delivery-header (die deze id weerspiegelt) als idempotentiesleutel zodat je handler elk event maar één keer verwerkt.
- Envelopvelden: id, type, created_at, group_id, data.
- type is een van de eventnamen uit de catalogus hieronder.
- data draagt de eventspecifieke velden.
- Gebruik id (en de X-Telm-Delivery-header) om retries te ontdubbelen.
2Eventcatalogus
Je abonneert een endpoint op elke deelverzameling van de catalogus. spam.detected gaat af wanneer de engine een bericht als spam markeert. message.suspicious gaat af in de monitoringmodus, wanneer de engine zou hebben gehandeld maar het bericht alleen een schaduwscore gaf. De ledenevents dekken mensen die binnenkomen, vertrekken en bestraft worden.
Het ping-event is speciaal: het maakt geen deel uit van de abonneerbare catalogus en wordt alleen verzonden wanneer je een testlevering voor een endpoint activeert, zodat je kunt bevestigen dat je ontvanger en handtekeningcontrole van begin tot eind werken.
- spam.detected — een bericht werd geclassificeerd als spam.
- message.suspicious — een schaduw- (monitoringmodus-)detectie.
- user.banned, user.kicked, user.muted — een moderatieactie werd toegepast.
- user.joined, user.left — een lid kwam binnen of verliet de groep.
- ping — een handmatig testevent, nooit afgevuurd door echte activiteit.
3Payloadvelden per event
Voor spam.detected en message.suspicious draagt het data-object message_id, user_id, username, de berichttekst (ingekort voor zeer lange berichten), de ondernomen actie, een categorie, een reden, de gedetecteerde taal en een betrouwbaarheidsscore. message.suspicious draagt daarnaast de schaduwscore.
Voor de ledenevents (user.joined, user.left, user.banned, user.kicked, user.muted) draagt het data-object user_id, username, first_name, een optionele message_id en een reden waar die van toepassing is. Eén onderliggend event kan meer dan één webhook opleveren — een spambericht dat een ban activeert wordt geleverd als zowel spam.detected als user.banned.
- Spam-events: message_id, user_id, username, text, action, category, reason, language, confidence (plus score voor message.suspicious).
- Ledenevents: user_id, username, first_name, message_id, reason.
- Eén incident kan meerdere events uitzenden; correleer ze op user_id en group_id.
4De HMAC-handtekening verifiëren
Elke levering is ondertekend zodat je zeker kunt zijn dat die echt van Telm kwam en niet is gemanipuleerd. Je krijgt een endpoint-geheim (het begint met whsec_) één keer, wanneer je het endpoint aanmaakt. Bewaar het en gebruik het om elk binnenkomend verzoek te verifiëren.
Om te verifiëren neem je de waarde van de X-Telm-Timestamp-header, voeg je er een punt aan toe, en voeg je vervolgens de exacte ruwe verzoekbody toe, en bereken je een HMAC-SHA256 van die tekenreeks met je endpoint-geheim als sleutel. Codeer het resultaat in hex en voorzie het van de prefix v1= — het moet gelijk zijn aan de X-Telm-Signature-header. Vergelijk met een constant-tijd-vergelijking, en wijs het verzoek af als de tijdstempel ouder is dan een paar minuten (vijf is een goede grens) om replays te blokkeren.
- X-Telm-Event — het eventtype.
- X-Telm-Delivery — de leverings-id (idempotentiesleutel).
- X-Telm-Timestamp — unix-seconden, ondertekend om replays te voorkomen.
- X-Telm-Signature — v1= plus de hex HMAC-SHA256 van tijdstempel, een punt, en de ruwe body.
5Levering, retries en automatisch uitschakelen
Een levering telt alleen als geslaagd wanneer je endpoint antwoordt met een 2xx-status. Al het andere — een niet-2xx-code, een time-out of een verbindingsfout — wordt als een mislukking behandeld en volgens een vast schema opnieuw geprobeerd: onmiddellijk, dan na 1 minuut, 5 minuten, 30 minuten, 2 uur en 6 uur, voor zes pogingen die ongeveer achtenhalf uur beslaan voordat de levering als mislukt wordt afgesloten.
Als een endpoint blijft falen — minstens twintig opeenvolgende mislukkingen zonder geslaagde levering gedurende drie dagen — schakelt Telm het automatisch uit zodat het stopt met verzenden naar een dode URL. Je kunt het weer inschakelen vanuit het dashboard zodra je ontvanger weer gezond is.
- Succes = HTTP 2xx. Antwoord snel (binnen ongeveer tien seconden) en doe zwaar werk asynchroon.
- Retry-schema: onmiddellijk, +1m, +5m, +30m, +2u, +6u (zes pogingen).
- Automatisch uitgeschakeld na 20 opeenvolgende mislukkingen zonder succes in 72 uur.
- Voor het registreren van webhooks is het Pro-plan of hoger vereist.