Webhooky — události moderace v reálném čase ve vašich systémech

1Co webhooky dělají

Místo dotazování API zaregistrujete URL a Telm na ni pošle podepsaný HTTP POST, kdykoli se ve vaší skupině něco stane. Takto dostanete události moderace do vlastních systémů — na dashboard, do datového skladu, do upozorňovacího kanálu — v reálném čase.

Endpointy webhooků spravujete přes API: zaregistrujete URL, zvolíte, které události odebírat, volitelně je omezíte na konkrétní skupiny, odešlete testovací ping a přečtete nedávný protokol doručení.

2Proč je posílání lepší než dotazování

Mohli byste volat endpoint žurnálu moderace na časovač a hledat nové události, ale to přidává latenci, spotřebovává kvótu a může minout přesný okamžik, kdy se něco stane. Webhooky model obracejí: Telm vám řekne v okamžiku, kdy událost nastane, takže vaše systémy reagují během sekund.

Typické využití zahrnuje zrcadlení banů do vlastních nástrojů pro správu, upozornění týmového kanálu, když je detekován nájezd, streamování detekcí do analytiky nebo spouštění workflow, když člen přijde či odejde.

• V reálném čase: o události se dozvíte, jakmile nastane, ne až při dalším dotazu.
• Efektivní: žádná opakovaná čtení, která ukusují z vaší denní kvóty.
• Kompletní: doručení se opakují, takže krátký výpadek na vaší straně události neztratí.

3Události, které lze odebírat

Existuje sedm odebíratelných typů událostí, které pokrývají verdikty o spamu, tresty a změny členství. Jediná moderovaná zpráva může vyprodukovat více než jednu událost — spamová zpráva, která skončí banem, vydá jak spam.detected, tak user.banned.

• spam.detected — engine označil zprávu jako spam.
• message.suspicious — stínová detekce (v monitorovacím režimu) se skóre.
• user.banned — člen byl zabanován.
• user.kicked — člen byl odstraněn.
• user.muted — člen byl umlčen.
• user.joined — člen vstoupil do skupiny.
• user.left — člen skupinu opustil.

4Obálka payloadu

Každé doručení je JSON obálka s malou, stabilní sadou polí nejvyšší úrovně a event-specifickým objektem data uvnitř. Můžete směrovat podle typu a času, aniž byste parsovali detaily, dokud je nepotřebujete.

• id — jedinečné id doručení; opakovaná doručení téže události znovu použijí stejné id, což je způsob, jak deduplikujete.
• type — typ události, jeden ze sedmi výše.
• created_at — kdy událost nastala, v RFC3339 UTC.
• group_id — skupina, do níž událost patří (pokud je to relevantní).
• data — event-specifický objekt: detaily zprávy a verdiktu u událostí spamu, detaily člena u událostí členství.

5Ověření, že doručení jsou skutečně od Telm

Každé doručení je podepsané, takže váš server může potvrdit, že požadavek skutečně přišel od Telm a nebyl při přenosu pozměněn. Ověřte podpis, než payloadu důvěřujete, a odmítněte cokoli, co neodpovídá.

Podpis je HMAC-SHA256 z časové značky a surového těla požadavku, klíčovaný vaším podpisovým tajemstvím endpointu. K ověření znovu vypočtěte HMAC nad hlavičkou časové značky a přesnými bajty, které jste obdrželi, a porovnejte jej s hlavičkou podpisu.

• X-Telm-Signature — podpis, formátovaný jako v1 následované hexadecimálním HMAC-SHA256 z časové značky spojené s tělem.
• X-Telm-Timestamp — časová značka v unixových sekundách, která je podepsána, takže můžete odmítnout zastaralá nebo přehraná doručení.
• X-Telm-Event — typ události, a X-Telm-Delivery — id doručení pro deduplikaci.
• Podpisové tajemství se zobrazí jen jednou, když endpoint vytvoříte, a začíná na whsec_. Ukládejte je bezpečně; je to jediná věc, která dokazuje, že je doručení pravé.

6Spolehlivé, deduplikované doručování

Doručování je alespoň jednou: Telm zajistí, že se událost k vám dostane, což znamená, že tatáž událost může občas dorazit dvakrát. Protože každé opakované doručení znovu použije stejné id doručení, deduplikujete tak, že si ukládáte id, která jste zpracovali, a opakování přeskakujete.

Pokud je váš endpoint nedostupný nebo vrátí chybu, doručení se opakuje podle pevného rozvrhu — zhruba po jedné minutě, pěti minutách, třiceti minutách, dvou hodinách a šesti hodinách, až šest pokusů v průběhu asi osmi a půl hodiny. Endpoint, který stále selhává, je automaticky vypnut, aby byly chráněny obě strany, a vlastník je upozorněn.

• Odpovězte rychle stavem 2xx; náročnou práci dělejte asynchronně až po potvrzení.
• Deduplikujte podle id doručení — nikdy podle obsahu payloadu.
• Endpoint, který selže asi dvacetkrát v řadě bez jediného úspěchu během 72hodinového okna, je automaticky vypnut; znovu jej zapněte, jakmile je váš server v pořádku.

7Správa endpointů a čtení protokolu

Endpointy webhooků registrujete, upravujete a odstraňujete přes API. Když jeden vytvoříte, obdržíte podpisové tajemství přesně jednou, zvolíte události k odběru a volitelně jej omezíte na konkrétní skupiny. Testovací volání odešle podepsaný ping, takže si můžete potvrdit, že vaše ověřování funguje, ještě než začne skutečný provoz.

Každý endpoint si vede protokol doručení, který si můžete zpětně přečíst a zjistit, co bylo odesláno, kdy a zda to bylo úspěšné — praktické pro ladění příjemce bez čekání na další živou událost.

• Vytvořte endpoint a ihned si zkopírujte tajemství whsec_.
• Odešlete testovací ping, abyste od začátku do konce ověřili svou kontrolu podpisu.
• Omezte endpoint na jednu skupinu, nebo jej nechte otevřený všem skupinám, které spravujete.
• Přečtěte si protokol doručení, abyste prohlédli nedávné pokusy a jejich výsledky.

8Osvědčené postupy a časté chyby

Robustní příjemce se řídí několika pravidly, která předcházejí nejčastějším problémům.

• Ověřujte podpis nad surovými bajty těla — naparsování do JSON a opětovná serializace mohou bajty změnit a kontrolu rozbít.
• Vraťte 2xx rychle a zpracovávejte později; pomalý handler způsobuje timeouty a zbytečná opakování.
• Udělejte zpracování idempotentní, aby opakovaně doručená událost nezapočítala dvakrát.
• Používejte HTTPS na veřejně dostupné URL; Telm blokuje interní a soukromé adresy a nenásleduje přesměrování.
• Držte tajemství whsec_ mimo protokoly a kód klienta.