Webhook-uri — evenimente de moderare în timp real în sistemele dumneavoastră

1Ce fac webhook-urile

În loc să interogați API-ul, înregistrați un URL, iar Telm îi trimite un POST HTTP semnat ori de câte ori se întâmplă ceva în grupul dumneavoastră. Așa aduceți evenimentele de moderare în propriile dumneavoastră sisteme — un tablou de bord, un depozit de date, un canal de alertare — în timp real.

Gestionați punctele finale de webhook prin API: înregistrați un URL, alegeți la ce evenimente vă abonați, opțional limitați-le la anumite grupuri, trimiteți un ping de test și citiți jurnalul recent de livrări.

2De ce push-ul e mai bun decât interogarea repetată

Ați putea apela punctul final al jurnalului la un interval de timp pentru a găsi evenimente noi, dar asta adaugă latență, cheltuiește cotă și poate rata momentul exact în care se întâmplă ceva. Webhook-urile inversează modelul: Telm vă spune în clipa în care se declanșează un eveniment, așa că sistemele dumneavoastră reacționează în câteva secunde.

Utilizările tipice includ oglindirea interdicțiilor în propriile dumneavoastră instrumente de administrare, alertarea unui canal de echipă când este detectat un raid, transmiterea detectărilor în analize sau declanșarea unui flux de lucru când un membru intră sau iese.

• În timp real: aflați despre un eveniment pe măsură ce se întâmplă, nu la următoarea dumneavoastră interogare.
• Eficient: fără citiri repetate care vă consumă cota zilnică.
• Complet: livrările sunt reîncercate, așa că o scurtă întrerupere din partea dumneavoastră nu pierde evenimente.

3Evenimente la care vă puteți abona

Există șapte tipuri de evenimente la care vă puteți abona, acoperind verdicte de spam, sancțiuni și schimbări de apartenență. Un singur mesaj moderat poate produce mai mult de un eveniment — un mesaj de spam care se termină cu o interdicție emite atât spam.detected, cât și user.banned.

• spam.detected — motorul a semnalat un mesaj drept spam.
• message.suspicious — o detectare shadow (modul monitorizare) cu un scor.
• user.banned — un membru a fost interzis.
• user.kicked — un membru a fost eliminat.
• user.muted — un membru a fost amuțit.
• user.joined — un membru a intrat în grup.
• user.left — un membru a părăsit grupul.

4Plicul sarcinii utile

Fiecare livrare este un plic JSON cu un set mic și stabil de câmpuri la nivel superior și un obiect data specific evenimentului în interior. Puteți direcționa pe baza tipului și a orei fără a analiza detaliile până când nu aveți nevoie de ele.

• id — un id de livrare unic; relivrările aceluiași eveniment reutilizează același id, care este modul în care deduplicați.
• type — tipul evenimentului, unul dintre cele șapte de mai sus.
• created_at — când s-a declanșat evenimentul, în RFC3339 UTC.
• group_id — grupul căruia îi aparține evenimentul (când este cazul).
• data — un obiect specific evenimentului: detaliile mesajului și ale verdictului pentru evenimentele de spam, detaliile membrului pentru evenimentele de apartenență.

5Verificarea faptului că livrările vin cu adevărat de la Telm

Fiecare livrare este semnată astfel încât serverul dumneavoastră să poată confirma că cererea a venit cu adevărat de la Telm și nu a fost modificată în tranzit. Validați semnătura înainte de a avea încredere în sarcina utilă și respingeți orice nu se potrivește.

Semnătura este un HMAC-SHA256 al marcajului de timp și al corpului brut al cererii, cu cheia secretului de semnare al punctului dumneavoastră final. Pentru a verifica, recalculați HMAC-ul peste antetul de marcaj de timp și octeții exacți pe care i-ați primit și comparați-l cu antetul de semnătură.

• X-Telm-Signature — semnătura, formatată ca v1 urmat de HMAC-SHA256 hexazecimal al marcajului de timp unit cu corpul.
• X-Telm-Timestamp — marcajul de timp în secunde unix care este semnat, ca să puteți respinge livrări învechite sau redate.
• X-Telm-Event — tipul evenimentului, iar X-Telm-Delivery — id-ul de livrare pentru deduplicare.
• Secretul de semnare este afișat o singură dată când creați punctul final și începe cu whsec_. Stocați-l în siguranță; este singurul lucru care dovedește că o livrare este autentică.

6Livrare fiabilă, deduplicată

Livrarea este cel-puțin-o-dată: Telm se asigură că un eveniment ajunge la dumneavoastră, ceea ce înseamnă că același eveniment poate ajunge ocazional de două ori. Deoarece fiecare relivrare reutilizează același id de livrare, deduplicați stocând id-urile pe care le-ați procesat și omițând repetările.

Dacă punctul dumneavoastră final este inaccesibil sau returnează o eroare, livrarea este reîncercată după un program fix — aproximativ după un minut, cinci minute, treizeci de minute, două ore și șase ore, până la șase încercări pe parcursul a aproximativ opt ore și jumătate. Un punct final care continuă să eșueze este dezactivat automat pentru a proteja ambele părți, iar proprietarul este notificat.

• Răspundeți rapid cu un status 2xx; efectuați munca grea asincron după confirmare.
• Deduplicați pe id-ul de livrare — niciodată pe conținutul sarcinii utile.
• Un punct final care eșuează de aproximativ douăzeci de ori la rând fără niciun succes într-o fereastră de 72 de ore este dezactivat automat; reactivați-l odată ce serverul dumneavoastră este sănătos.

7Gestionarea punctelor finale și citirea jurnalului

Înregistrați, editați și eliminați puncte finale de webhook prin API. Când creați unul, primiți secretul de semnare exact o dată, alegeți evenimentele la care vă abonați și opțional îl limitați la anumite grupuri. Un apel de test trimite un ping semnat, astfel încât să puteți confirma că verificarea dumneavoastră funcționează înainte ca traficul real să înceapă.

Fiecare punct final păstrează un jurnal de livrări pe care îl puteți reciti pentru a vedea ce a fost trimis, când și dacă a reușit — util pentru depanarea unui receptor fără a aștepta următorul eveniment live.

• Creați un punct final și copiați secretul whsec_ imediat.
• Trimiteți un ping de test pentru a valida verificarea semnăturii de la un capăt la altul.
• Limitați un punct final la un singur grup sau lăsați-l deschis tuturor grupurilor pe care le administrați.
• Citiți jurnalul de livrări pentru a inspecta încercările recente și rezultatele lor.

8Bune practici și greșeli frecvente

Un receptor robust urmează câteva reguli care previn cele mai frecvente probleme.

• Verificați semnătura peste octeții bruți ai corpului — analizarea în JSON mai întâi și reserializarea pot schimba octeții și strica verificarea.
• Returnați 2xx rapid și procesați mai târziu; un handler lent cauzează timeout-uri și reîncercări inutile.
• Faceți gestionarea idempotentă, astfel încât un eveniment relivrat să nu numere de două ori.
• Folosiți HTTPS pe un URL accesibil public; Telm blochează adresele interne și private și nu urmează redirecționări.
• Păstrați secretul whsec_ în afara jurnalelor și a codului de partea clientului.