Webhooks – realtidsmoderationshändelser i dina system

1Vad webhooks gör

I stället för att polla API:t registrerar du en URL och Telm skickar en signerad HTTP POST till den när något händer i din grupp. Så här får du moderationshändelser in i dina egna system – en dashboard, ett datalager, en varningskanal – i realtid.

Du hanterar webhook-endpoints genom API:t: registrera en URL, välj vilka händelser att prenumerera på, begränsa dem valfritt till specifika grupper, skicka en test-ping, och läs den senaste leveransloggen.

2Varför push slår polling

Du skulle kunna anropa journal-endpointen på en timer för att hitta nya händelser, men det lägger till latens, spenderar kvot, och kan missa det exakta ögonblick något händer. Webhooks vänder på modellen: Telm berättar för dig i det ögonblick en händelse utlöses, så att dina system reagerar på sekunder.

Typiska användningsområden inkluderar att spegla bannlysningar in i dina egna administratörsverktyg, att varna en teamkanal när en raid upptäcks, att strömma detektioner in i analys, eller att utlösa ett arbetsflöde när en medlem ansluter eller kopplar från.

• Realtid: du får veta om en händelse när den händer, inte vid din nästa pollning.
• Effektivt: inga upprepade läsningar som äter in i din dagliga kvot.
• Fullständigt: leveranser görs om, så att ett kort avbrott på din sida inte förlorar händelser.

3Händelser du kan prenumerera på

Det finns sju prenumererbara händelsetyper, som täcker spamutslag, straff och medlemskapsförändringar. Ett enda modererat meddelande kan producera mer än en händelse – ett spammeddelande som slutar i en bannlysning avger både spam.detected och user.banned.

• spam.detected – motorn flaggade ett meddelande som spam.
• message.suspicious – en skugg-detektion (övervakningsläge) med en poäng.
• user.banned – en medlem bannlystes.
• user.kicked – en medlem togs bort.
• user.muted – en medlem tystades.
• user.joined – en medlem anslöt till gruppen.
• user.left – en medlem lämnade gruppen.

4Payload-kuvertet

Varje leverans är ett JSON-kuvert med en liten, stabil uppsättning fält på toppnivå och ett händelsespecifikt data-objekt inuti. Du kan dirigera på typen och tiden utan att tolka detaljerna förrän du behöver dem.

• id – ett unikt delivery id; omleveranser av samma händelse återanvänder samma id, vilket är hur du deduplicerar.
• type – händelsetypen, en av de sju ovan.
• created_at – när händelsen utlöstes, i RFC3339 UTC.
• group_id – gruppen händelsen tillhör (när tillämpligt).
• data – ett händelsespecifikt objekt: meddelande- och utslagsdetaljer för spamhändelser, medlemsdetaljer för medlemskapshändelser.

5Att verifiera att leveranser verkligen är från Telm

Varje leverans signeras så att din server kan bekräfta att förfrågan verkligen kom från Telm och inte manipulerades under överföringen. Validera signaturen innan du litar på payloaden, och avvisa allt som inte matchar.

Signaturen är en HMAC-SHA256 av tidsstämpeln och den råa förfrågningskroppen, nycklad med din endpoints signeringshemlighet. För att verifiera, beräkna om HMAC över tidsstämpel-rubriken och de exakta byte du tog emot, och jämför den med signatur-rubriken.

• X-Telm-Signature – signaturen, formaterad som v1 följt av hex-HMAC-SHA256 av tidsstämpeln sammanfogad med kroppen.
• X-Telm-Timestamp – unix-sekunder-tidsstämpeln som signeras, så att du kan avvisa gamla eller återspelade leveranser.
• X-Telm-Event – händelsetypen, och X-Telm-Delivery – delivery id för deduplicering.
• Signeringshemligheten visas en gång när du skapar endpointen och börjar med whsec_. Lagra den säkert; den är det enda som bevisar att en leverans är äkta.

6Pålitlig, deduplicerad leverans

Leverans är minst-en-gång: Telm ser till att en händelse når dig, vilket betyder att samma händelse ibland kan komma två gånger. Eftersom varje omleverans återanvänder samma delivery id deduplicerar du genom att lagra de id:n du har bearbetat och hoppa över upprepningar.

Om din endpoint är onåbar eller returnerar ett fel görs leveransen om enligt ett fast schema – ungefär efter en minut, fem minuter, trettio minuter, två timmar och sex timmar, upp till sex försök över ungefär åtta och en halv timme. En endpoint som fortsätter att misslyckas inaktiveras automatiskt för att skydda båda sidor, och ägaren meddelas.

• Svara snabbt med en 2xx-status; gör tungt arbete asynkront efter att ha bekräftat.
• Deduplicera på delivery id – aldrig på payload-innehållet.
• En endpoint som misslyckas ungefär tjugo gånger i rad utan någon framgång inom ett 72-timmarsfönster inaktiveras automatiskt; återaktivera den när din server är frisk.

7Att hantera endpoints och läsa loggen

Du registrerar, redigerar och tar bort webhook-endpoints genom API:t. När du skapar en tar du emot signeringshemligheten exakt en gång, väljer händelserna att prenumerera på, och begränsar den valfritt till specifika grupper. Ett test-anrop skickar en signerad ping så att du kan bekräfta att din verifiering fungerar innan riktig trafik börjar.

Varje endpoint håller en leveranslogg du kan läsa tillbaka för att se vad som skickades, när, och om det lyckades – praktiskt för att felsöka en mottagare utan att vänta på nästa live-händelse.

• Skapa en endpoint och kopiera whsec_-hemligheten omedelbart.
• Skicka en test-ping för att validera din signaturkontroll från början till slut.
• Begränsa en endpoint till en grupp eller lämna den öppen för alla grupper du administrerar.
• Läs leveransloggen för att inspektera de senaste försöken och deras utfall.

8Bästa praxis och vanliga misstag

En robust mottagare följer några få regler som förebygger de vanligaste problemen.

• Verifiera signaturen över de råa kropps-byten – att först tolka till JSON och serialisera om kan ändra byten och bryta kontrollen.
• Returnera 2xx snabbt och bearbeta senare; en långsam hanterare orsakar timeouts och onödiga omförsök.
• Gör hanteringen idempotent så att en omlevererad händelse inte dubbelräknas.
• Använd HTTPS på en offentligt nåbar URL; Telm blockerar interna och privata adresser och följer inte omdirigeringar.
• Håll whsec_-hemligheten borta från loggar och klientkod.