Telm kan pusha modereringshändelser till din server i realtid. Du registrerar en endpoint, väljer vilka händelser du vill ta emot, och Telm skickar en signerad POST för var och en. Varje leverans bär en HMAC-SHA256-signatur som du verifierar med din endpoint-hemlighet. Misslyckade leveranser görs om enligt ett schema; en permanent onåbar endpoint inaktiveras automatiskt.
1Händelsekuvertet
Varje webhook är en HTTP POST med en JSON-kropp i ett gemensamt kuvert. Kuvertet har ett id (en unik leveransidentifierare för avdubblering), en type (händelsenamnet), en created_at-tidsstämpel, det group_id händelsen tillhör, och ett data-objekt vars form beror på händelsetypen.
id:t är deterministiskt för verkliga händelser, så om samma händelse levereras två gånger — till exempel efter ett omförsök — får du samma id båda gångerna. Använd X-Telm-Delivery-huvudet (som speglar detta id) som en idempotensnyckel så att din hanterare behandlar varje händelse bara en gång.
- Kuvertfält: id, type, created_at, group_id, data.
- type är ett av händelsenamnen från katalogen nedan.
- data bär de händelsespecifika fälten.
- Använd id (och X-Telm-Delivery-huvudet) för att avdubbla omförsök.
2Händelsekatalog
Du prenumererar en endpoint på valfri delmängd av katalogen. spam.detected utlöses när motorn flaggar ett meddelande som spam. message.suspicious utlöses i övervakningsläge, när motorn skulle ha agerat men bara skuggpoängsatte meddelandet. Medlemshändelserna täcker personer som går in, lämnar och blir bestraffade.
ping-händelsen är särskild: den är inte del av den prenumererbara katalogen och skickas bara när du utlöser en testleverans för en endpoint, så att du kan bekräfta att din mottagare och signaturkontroll fungerar hela vägen.
- spam.detected — ett meddelande klassificerades som spam.
- message.suspicious — en skugg-detektering (övervakningsläge).
- user.banned, user.kicked, user.muted — en modereringsåtgärd tillämpades.
- user.joined, user.left — en medlem gick in i eller lämnade gruppen.
- ping — en manuell testhändelse, aldrig utlöst av verklig aktivitet.
3Nyttolastfält per händelse
För spam.detected och message.suspicious bär data-objektet message_id, user_id, username, meddelandetexten (avkortad för mycket långa meddelanden), åtgärden som vidtogs, en category, en reason, det detekterade språket, och en konfidenspoäng. message.suspicious bär dessutom skuggpoängen.
För medlemshändelserna (user.joined, user.left, user.banned, user.kicked, user.muted) bär data-objektet user_id, username, first_name, ett valfritt message_id, och en reason där en sådan gäller. En underliggande händelse kan producera mer än en webhook — ett spammeddelande som utlöser ett bann levereras som både spam.detected och user.banned.
- Spamhändelser: message_id, user_id, username, text, action, category, reason, language, confidence (plus score för message.suspicious).
- Medlemshändelser: user_id, username, first_name, message_id, reason.
- En enda incident kan avge flera händelser; korrelera dem med user_id och group_id.
4Att verifiera HMAC-signaturen
Varje leverans är signerad så att du kan vara säker på att den verkligen kom från Telm och inte manipulerades. Du får en endpoint-hemlighet (den börjar med whsec_) en gång, när du skapar endpointen. Förvara den och använd den för att verifiera varje inkommande anrop.
För att verifiera, ta värdet på X-Telm-Timestamp-huvudet, lägg till en punkt, lägg sedan till den exakta råa anropskroppen, och beräkna en HMAC-SHA256 av den strängen med din endpoint-hemlighet som nyckel. Hex-koda resultatet och prefixa det med v1= — det måste vara lika med X-Telm-Signature-huvudet. Jämför med en jämförelse i konstant tid, och avvisa anropet om tidsstämpeln är äldre än några minuter (fem är en bra gräns) för att blockera återuppspelningar.
- X-Telm-Event — händelsetypen.
- X-Telm-Delivery — leverans-id:t (idempotensnyckel).
- X-Telm-Timestamp — unix-sekunder, signerade för att förhindra återuppspelningar.
- X-Telm-Signature — v1= plus hex-HMAC-SHA256 av tidsstämpeln, en punkt, och den råa kroppen.
5Leverans, omförsök och autoinaktivering
En leverans räknas som lyckad bara om din endpoint svarar med en 2xx-status. Allt annat — en icke-2xx-kod, en timeout, eller ett anslutningsfel — behandlas som ett misslyckande och görs om enligt ett fast schema: omedelbart, sedan efter 1 minut, 5 minuter, 30 minuter, 2 timmar och 6 timmar, i sex försök som spänner över ungefär åtta och en halv timme innan leveransen stängs som misslyckad.
Om en endpoint fortsätter misslyckas — minst tjugo misslyckanden i rad utan någon lyckad leverans på tre dagar — inaktiverar Telm den automatiskt så att den slutar skicka till en död URL. Du kan återaktivera den från dashboarden när din mottagare är frisk igen.
- Lyckat = HTTP 2xx. Svara snabbt (inom ungefär tio sekunder) och gör tungt arbete asynkront.
- Omförsöksschema: omedelbart, +1m, +5m, +30m, +2h, +6h (sex försök).
- Autoinaktiveras efter 20 misslyckanden i rad utan framgång på 72 timmar.
- Att registrera webhooks kräver Pro-planen eller högre.