Webhooks — Echtzeit-Moderationsereignisse in Ihren Systemen

1Was Webhooks tun

Statt die API abzufragen, registrieren Sie eine URL, und Telm sendet einen signierten HTTP-POST an sie, sobald in Ihrer Gruppe etwas passiert. So bringen Sie Moderationsereignisse in Echtzeit in Ihre eigenen Systeme — ein Dashboard, ein Data Warehouse, einen Alarmkanal.

Sie verwalten Webhook-Endpunkte über die API: eine URL registrieren, wählen, welche Ereignisse abonniert werden, sie optional auf bestimmte Gruppen beschränken, einen Test-Ping senden und das jüngste Zustellungsprotokoll lesen.

2Warum Push besser ist als Polling

Sie könnten den Journal-Endpunkt zeitgesteuert aufrufen, um neue Ereignisse zu finden, aber das erhöht die Latenz, verbraucht Kontingent und kann den genauen Moment verpassen, in dem etwas passiert. Webhooks drehen das Modell um: Telm teilt es Ihnen im Augenblick des Ereignisses mit, sodass Ihre Systeme in Sekunden reagieren.

Typische Anwendungen umfassen das Spiegeln von Banns in Ihre eigenen Admin-Tools, das Alarmieren eines Team-Kanals, wenn ein Raid erkannt wird, das Streamen von Erkennungen in Analysen oder das Auslösen eines Workflows, wenn ein Mitglied beitritt oder austritt.

• Echtzeit: Sie erfahren von einem Ereignis, während es geschieht, nicht erst bei Ihrer nächsten Abfrage.
• Effizient: keine wiederholten Abfragen, die in Ihr Tageskontingent einschneiden.
• Vollständig: Zustellungen werden wiederholt, sodass ein kurzer Ausfall auf Ihrer Seite keine Ereignisse verliert.

3Ereignisse, die Sie abonnieren können

Es gibt sieben abonnierbare Ereignistypen, die Spam-Urteile, Strafen und Mitgliedschaftsänderungen abdecken. Eine einzige moderierte Nachricht kann mehr als ein Ereignis erzeugen — eine Spam-Nachricht, die in einem Bann endet, gibt sowohl spam.detected als auch user.banned aus.

• spam.detected — die Engine hat eine Nachricht als Spam markiert.
• message.suspicious — eine Erkennung im Schatten-(Überwachungs-)Modus mit einem Score.
• user.banned — ein Mitglied wurde gebannt.
• user.kicked — ein Mitglied wurde entfernt.
• user.muted — ein Mitglied wurde stummgeschaltet.
• user.joined — ein Mitglied ist der Gruppe beigetreten.
• user.left — ein Mitglied hat die Gruppe verlassen.

4Der Payload-Umschlag

Jede Zustellung ist ein JSON-Umschlag mit einem kleinen, stabilen Satz von Feldern der obersten Ebene und einem ereignisspezifischen data-Objekt darin. Sie können nach Typ und Zeitpunkt routen, ohne die Details zu parsen, bis Sie sie benötigen.

• id — eine eindeutige Zustellungs-ID; erneute Zustellungen desselben Ereignisses verwenden dieselbe ID wieder, worüber Sie deduplizieren.
• type — der Ereignistyp, einer der sieben oben genannten.
• created_at — wann das Ereignis ausgelöst wurde, in RFC3339 UTC.
• group_id — die Gruppe, zu der das Ereignis gehört (sofern zutreffend).
• data — ein ereignisspezifisches Objekt: Nachrichten- und Urteilsdetails bei Spam-Ereignissen, Mitgliedsdetails bei Mitgliedschaftsereignissen.

5Überprüfen, dass Zustellungen wirklich von Telm stammen

Jede Zustellung ist signiert, sodass Ihr Server bestätigen kann, dass die Anfrage tatsächlich von Telm kam und unterwegs nicht manipuliert wurde. Validieren Sie die Signatur, bevor Sie der Payload vertrauen, und weisen Sie alles zurück, was nicht übereinstimmt.

Die Signatur ist ein HMAC-SHA256 aus dem Zeitstempel und dem rohen Anfrage-Body, mit Ihrem Endpunkt-Signaturgeheimnis als Schlüssel. Zum Überprüfen berechnen Sie den HMAC über den Zeitstempel-Header und die exakten empfangenen Bytes neu und vergleichen ihn mit dem Signatur-Header.

• X-Telm-Signature — die Signatur, formatiert als v1 gefolgt vom hexadezimalen HMAC-SHA256 aus Zeitstempel und Body verbunden.
• X-Telm-Timestamp — der signierte Zeitstempel in Unix-Sekunden, sodass Sie veraltete oder wiederholte Zustellungen zurückweisen können.
• X-Telm-Event — der Ereignistyp, und X-Telm-Delivery — die Zustellungs-ID zur Deduplizierung.
• Das Signaturgeheimnis wird einmal angezeigt, wenn Sie den Endpunkt erstellen, und beginnt mit whsec_. Speichern Sie es sicher; es ist das Einzige, das eine Zustellung als echt beweist.

6Zuverlässige, deduplizierte Zustellung

Die Zustellung erfolgt mindestens einmal: Telm stellt sicher, dass ein Ereignis Sie erreicht, was bedeutet, dass dasselbe Ereignis gelegentlich zweimal ankommen kann. Da jede erneute Zustellung dieselbe delivery id wiederverwendet, entfernen Sie Duplikate, indem Sie die verarbeiteten ids speichern und Wiederholungen überspringen.

Wenn Ihr Endpunkt nicht erreichbar ist oder einen Fehler zurückgibt, wird die Zustellung nach einem festen Zeitplan wiederholt — etwa nach einer Minute, fünf Minuten, dreißig Minuten, zwei Stunden und sechs Stunden, bis zu sechs Versuchen über etwa achteinhalb Stunden. Ein Endpunkt, der ständig ausfällt, wird automatisch deaktiviert, um beide Seiten zu schützen, und der Eigentümer wird benachrichtigt.

• Antworten Sie schnell mit einem 2xx-Status; erledigen Sie schwere Arbeit asynchron nach der Bestätigung.
• Deduplizieren Sie über die Zustellungs-ID — niemals über den Payload-Inhalt.
• Ein Endpunkt, der etwa zwanzigmal in Folge ohne Erfolg innerhalb eines 72-Stunden-Fensters ausfällt, wird automatisch deaktiviert; aktivieren Sie ihn wieder, sobald Ihr Server gesund ist.

7Endpunkte verwalten und das Protokoll lesen

Sie registrieren, bearbeiten und entfernen Webhook-Endpunkte über die API. Wenn Sie einen erstellen, erhalten Sie das Signaturgeheimnis genau einmal, wählen die zu abonnierenden Ereignisse und beschränken ihn optional auf bestimmte Gruppen. Ein Testaufruf sendet einen signierten Ping, sodass Sie bestätigen können, dass Ihre Überprüfung funktioniert, bevor echter Verkehr beginnt.

Jeder Endpunkt führt ein Zustellungsprotokoll, das Sie zurücklesen können, um zu sehen, was wann gesendet wurde und ob es erfolgreich war — praktisch, um einen Empfänger zu debuggen, ohne auf das nächste Live-Ereignis zu warten.

• Erstellen Sie einen Endpunkt und kopieren Sie das whsec_-Geheimnis sofort.
• Senden Sie einen Test-Ping, um Ihre Signaturprüfung durchgängig zu validieren.
• Beschränken Sie einen Endpunkt auf eine Gruppe oder lassen Sie ihn für alle von Ihnen verwalteten Gruppen offen.
• Lesen Sie das Zustellungsprotokoll, um jüngste Versuche und ihre Ergebnisse zu prüfen.

8Best Practices und häufige Fehler

Ein robuster Empfänger befolgt einige Regeln, die die häufigsten Probleme verhindern.

• Überprüfen Sie die Signatur über die rohen Body-Bytes — erst nach JSON zu parsen und neu zu serialisieren kann die Bytes verändern und die Prüfung brechen.
• Geben Sie schnell 2xx zurück und verarbeiten Sie später; ein langsamer Handler verursacht Timeouts und unnötige Wiederholungen.
• Machen Sie die Verarbeitung idempotent, damit ein erneut zugestelltes Ereignis nicht doppelt gezählt wird.
• Verwenden Sie HTTPS an einer öffentlich erreichbaren URL; Telm blockiert interne und private Adressen und folgt keinen Weiterleitungen.
• Halten Sie das whsec_-Geheimnis aus Protokollen und Client-Code heraus.