Webhooks — realtime moderatiegebeurtenissen in je systemen

1Wat webhooks doen

In plaats van de API te pollen registreer je een URL, en Telm stuurt daar een ondertekende HTTP POST naartoe telkens als er iets in je groep gebeurt. Zo krijg je moderatiegebeurtenissen realtime in je eigen systemen — een dashboard, een datawarehouse, een waarschuwingskanaal.

Je beheert webhook-endpoints via de API: registreer een URL, kies op welke gebeurtenissen je je abonneert, beperk ze eventueel tot specifieke groepen, stuur een testping, en lees het recente afleverlogboek.

2Waarom pushen beter is dan pollen

Je zou het journaal-endpoint op een timer kunnen aanroepen om nieuwe gebeurtenissen te vinden, maar dat kost extra vertraging en quotum, en kan het exacte moment missen waarop iets gebeurt. Webhooks draaien dat model om: Telm laat het je weten zodra een gebeurtenis plaatsvindt, zodat je systemen binnen seconden reageren.

Typische toepassingen: bans spiegelen naar je eigen beheertools, een teamkanaal waarschuwen wanneer een raid wordt gedetecteerd, detecties naar je analyses streamen, of een workflow starten wanneer een lid joint of vertrekt.

• Realtime: je hoort van een gebeurtenis op het moment zelf, niet pas bij je volgende poll.
• Efficiënt: geen herhaalde uitlezingen die je dagelijkse quotum opeten.
• Compleet: afleveringen worden opnieuw geprobeerd, zodat een korte storing aan jouw kant geen gebeurtenissen verliest.

3Gebeurtenissen waarop je je kunt abonneren

Er zijn zeven gebeurtenistypen waarop je je kunt abonneren; ze dekken spamoordelen, straffen en lidmaatschapswijzigingen. Eén gemodereerd bericht kan meer dan één gebeurtenis opleveren — een spambericht dat op een ban uitloopt, verstuurt zowel spam.detected als user.banned.

• spam.detected — de engine markeerde een bericht als spam.
• message.suspicious — een schaduw- (monitormodus-)detectie met een score.
• user.banned — een lid werd gebanned.
• user.kicked — een lid werd verwijderd.
• user.muted — een lid werd gemute.
• user.joined — een lid joinde de groep.
• user.left — een lid verliet de groep.

4De payload-envelop

Elke aflevering is een JSON-envelop met een kleine, stabiele set velden op het bovenste niveau en daarbinnen een gebeurtenisspecifiek data-object. Je kunt op het type en de tijd routeren zonder de details te parseren tot je ze nodig hebt.

• id — een unieke delivery-id; herafleveringen van dezelfde gebeurtenis hergebruiken dezelfde id, en zo dedupliceer je.
• type — het gebeurtenistype, een van de zeven hierboven.
• created_at — wanneer de gebeurtenis plaatsvond, in RFC3339 UTC.
• group_id — de groep waartoe de gebeurtenis behoort (indien van toepassing).
• data — een gebeurtenisspecifiek object: bericht- en oordeeldetails voor spamgebeurtenissen, liddetails voor lidmaatschapsgebeurtenissen.

5Verifiëren dat afleveringen echt van Telm komen

Elke aflevering is ondertekend, zodat je server kan bevestigen dat het verzoek echt van Telm kwam en onderweg niet is gemanipuleerd. Valideer de handtekening voordat je de payload vertrouwt, en wijs alles af wat niet klopt.

De handtekening is een HMAC-SHA256 van de tijdstempel en de ruwe verzoek-body, met het ondertekeningsgeheim van je endpoint als sleutel. Om te verifiëren bereken je de HMAC opnieuw over de tijdstempelheader en de exacte bytes die je hebt ontvangen, en vergelijk je die met de handtekeningheader.

• X-Telm-Signature — de handtekening, geformatteerd als v1 gevolgd door de hex-HMAC-SHA256 van de tijdstempel samengevoegd met de body.
• X-Telm-Timestamp — de tijdstempel in unix-seconden die wordt ondertekend, zodat je verouderde of opnieuw afgespeelde afleveringen kunt afwijzen.
• X-Telm-Event — het gebeurtenistype, en X-Telm-Delivery — de delivery-id voor deduplicatie.
• Het ondertekeningsgeheim wordt eenmaal getoond wanneer je het endpoint aanmaakt en begint met whsec_. Bewaar het veilig; het is het enige wat bewijst dat een aflevering echt is.

6Betrouwbare, gededupliceerde aflevering

Aflevering is at-least-once: Telm zorgt dat een gebeurtenis je bereikt, wat betekent dat dezelfde gebeurtenis af en toe twee keer kan binnenkomen. Omdat elke heraflevering dezelfde delivery-id hergebruikt, dedupliceer je door de ids die je al hebt verwerkt op te slaan en herhalingen over te slaan.

Als je endpoint onbereikbaar is of een fout teruggeeft, wordt de aflevering volgens een vast schema opnieuw geprobeerd — ruwweg na één minuut, vijf minuten, dertig minuten, twee uur en zes uur, tot zes pogingen over ongeveer achtenhalf uur. Een endpoint dat blijft falen wordt automatisch uitgeschakeld om beide kanten te beschermen, en de eigenaar krijgt bericht.

• Reageer snel met een 2xx-status; doe zwaar werk asynchroon nadat je hebt bevestigd.
• Dedupliceer op de delivery-id — nooit op de inhoud van de payload.
• Een endpoint dat ongeveer twintig keer op rij faalt zonder succes binnen een venster van 72 uur wordt automatisch uitgeschakeld; schakel het weer in zodra je server weer gezond is.

7Endpoints beheren en het logboek lezen

Je registreert, bewerkt en verwijdert webhook-endpoints via de API. Wanneer je er een aanmaakt, krijg je het ondertekeningsgeheim precies één keer te zien, kies je de gebeurtenissen waarop je je abonneert, en beperk je het eventueel tot specifieke groepen. Een testaanroep stuurt een ondertekende ping, zodat je kunt bevestigen dat je verificatie werkt voordat het echte verkeer begint.

Elk endpoint houdt een afleverlogboek bij dat je kunt teruglezen om te zien wat er is verzonden, wanneer, en of het is geslaagd — handig om een ontvanger te debuggen zonder op de volgende live gebeurtenis te wachten.

• Maak een endpoint aan en kopieer meteen het whsec_-geheim.
• Stuur een testping om je handtekeningcontrole van begin tot eind te valideren.
• Beperk een endpoint tot één groep of laat het open voor alle groepen die je beheert.
• Lees het afleverlogboek om recente pogingen en hun uitkomsten te bekijken.

8Best practices en veelgemaakte fouten

Een robuuste ontvanger volgt een paar regels die de meest voorkomende problemen voorkomen.

• Verifieer de handtekening over de ruwe body-bytes — eerst naar JSON parseren en opnieuw serialiseren kan de bytes veranderen en de controle laten mislukken.
• Stuur snel 2xx terug en verwerk daarna pas; een trage handler veroorzaakt time-outs en onnodige herpogingen.
• Maak de afhandeling idempotent, zodat een opnieuw afgeleverde gebeurtenis niet dubbel telt.
• Gebruik HTTPS op een publiek bereikbare URL; Telm blokkeert interne en privé-adressen en volgt geen redirects.
• Houd het whsec_-geheim uit logboeken en clientcode.