Telm kann Moderationsereignisse in Echtzeit an Ihren Server pushen. Sie registrieren einen Endpunkt, wählen, welche Ereignisse Sie empfangen möchten, und Telm sendet für jedes einen signierten POST. Jede Zustellung trägt eine HMAC-SHA256-Signatur, die Sie mit Ihrem Endpunkt-Geheimnis verifizieren. Fehlgeschlagene Zustellungen werden nach einem Zeitplan wiederholt; ein dauerhaft unerreichbarer Endpunkt wird automatisch deaktiviert.
1Der Ereignis-Umschlag
Jeder Webhook ist ein HTTP-POST mit einem JSON-Body in einem gemeinsamen Umschlag. Der Umschlag hat eine id (eine eindeutige Zustellungskennung zur Duplikaterkennung), einen type (den Ereignisnamen), einen created_at-Zeitstempel, die group_id, zu der das Ereignis gehört, und ein data-Objekt, dessen Form vom Ereignistyp abhängt.
Die id ist für echte Ereignisse deterministisch, sodass Sie, wenn dasselbe Ereignis zweimal zugestellt wird — zum Beispiel nach einer Wiederholung —, beide Male dieselbe id erhalten. Verwenden Sie den X-Telm-Delivery-Header (der diese id widerspiegelt) als Idempotenzschlüssel, damit Ihr Handler jedes Ereignis nur einmal verarbeitet.
- Umschlagfelder: id, type, created_at, group_id, data.
- type ist einer der Ereignisnamen aus dem Katalog unten.
- data trägt die ereignisspezifischen Felder.
- Verwenden Sie id (und den X-Telm-Delivery-Header), um Wiederholungen zu deduplizieren.
2Ereigniskatalog
Sie abonnieren einen Endpunkt für eine beliebige Teilmenge des Katalogs. spam.detected wird ausgelöst, wenn die Engine eine Nachricht als Spam markiert. message.suspicious wird im Beobachtungsmodus ausgelöst, wenn die Engine gehandelt hätte, die Nachricht aber nur im Schattenmodus bewertet hat. Die Mitgliederereignisse decken Personen ab, die beitreten, verlassen und bestraft werden.
Das ping-Ereignis ist besonders: Es ist nicht Teil des abonnierbaren Katalogs und wird nur gesendet, wenn Sie eine Testzustellung für einen Endpunkt auslösen, damit Sie bestätigen können, dass Ihr Empfänger und Ihre Signaturprüfung durchgängig funktionieren.
- spam.detected — eine Nachricht wurde als Spam klassifiziert.
- message.suspicious — eine Schatten-Erkennung (Beobachtungsmodus).
- user.banned, user.kicked, user.muted — eine Moderationsaktion wurde angewendet.
- user.joined, user.left — ein Mitglied ist der Gruppe beigetreten oder hat sie verlassen.
- ping — ein manuelles Testereignis, das niemals durch echte Aktivität ausgelöst wird.
3Payload-Felder pro Ereignis
Bei spam.detected und message.suspicious trägt das data-Objekt message_id, user_id, username, den Nachrichtentext (bei sehr langen Nachrichten gekürzt), die durchgeführte Aktion, eine category, einen reason, die erkannte Sprache und einen Konfidenzwert. message.suspicious trägt zusätzlich den Schattenwert.
Bei den Mitgliederereignissen (user.joined, user.left, user.banned, user.kicked, user.muted) trägt das data-Objekt user_id, username, first_name, eine optionale message_id und einen reason, sofern zutreffend. Ein einzelnes zugrunde liegendes Ereignis kann mehr als einen Webhook erzeugen — eine Spam-Nachricht, die einen Bann auslöst, wird sowohl als spam.detected als auch als user.banned zugestellt.
- Spam-Ereignisse: message_id, user_id, username, text, action, category, reason, language, confidence (plus score bei message.suspicious).
- Mitgliederereignisse: user_id, username, first_name, message_id, reason.
- Ein einzelner Vorfall kann mehrere Ereignisse aussenden; korrelieren Sie sie über user_id und group_id.
4Die HMAC-Signatur verifizieren
Jede Zustellung wird signiert, sodass Sie sicher sein können, dass sie wirklich von Telm kam und nicht manipuliert wurde. Sie erhalten ein Endpunkt-Geheimnis (es beginnt mit whsec_) einmalig, wenn Sie den Endpunkt erstellen. Speichern Sie es und verwenden Sie es, um jede eingehende Anfrage zu verifizieren.
Zum Verifizieren nehmen Sie den Wert des X-Telm-Timestamp-Headers, hängen einen Punkt an und danach den exakten rohen Anfrage-Body, und berechnen einen HMAC-SHA256 dieser Zeichenfolge mit Ihrem Endpunkt-Geheimnis als Schlüssel. Kodieren Sie das Ergebnis in Hex und stellen Sie v1= voran — es muss dem X-Telm-Signature-Header entsprechen. Vergleichen Sie mit einem laufzeitkonstanten Vergleich und lehnen Sie die Anfrage ab, wenn der Zeitstempel älter als ein paar Minuten ist (fünf sind eine gute Grenze), um Replays zu blockieren.
- X-Telm-Event — der Ereignistyp.
- X-Telm-Delivery — die Zustellungs-id (Idempotenzschlüssel).
- X-Telm-Timestamp — Unix-Sekunden, signiert, um Replays zu verhindern.
- X-Telm-Signature — v1= plus der Hex-HMAC-SHA256 aus Zeitstempel, einem Punkt und dem rohen Body.
5Zustellung, Wiederholungen und automatische Deaktivierung
Eine Zustellung gilt nur dann als erfolgreich, wenn Ihr Endpunkt mit einem 2xx-Status antwortet. Alles andere — ein Nicht-2xx-Code, ein Timeout oder ein Verbindungsfehler — wird als Fehlschlag behandelt und nach einem festen Zeitplan wiederholt: sofort, dann nach 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden und 6 Stunden, für sechs Versuche über rund achteinhalb Stunden, bevor die Zustellung als fehlgeschlagen geschlossen wird.
Wenn ein Endpunkt weiterhin fehlschlägt — mindestens zwanzig aufeinanderfolgende Fehlschläge ohne erfolgreiche Zustellung über drei Tage —, deaktiviert Telm ihn automatisch, sodass er aufhört, an eine tote URL zu senden. Sie können ihn im Dashboard wieder aktivieren, sobald Ihr Empfänger wieder gesund ist.
- Erfolg = HTTP 2xx. Antworten Sie schnell (innerhalb von etwa zehn Sekunden) und erledigen Sie aufwendige Arbeit asynchron.
- Wiederholungsplan: sofort, +1m, +5m, +30m, +2h, +6h (sechs Versuche).
- Automatisch deaktiviert nach 20 Fehlschlägen in Folge ohne Erfolg innerhalb von 72 Stunden.
- Das Registrieren von Webhooks erfordert den Pro-Plan oder höher.