Webhooks — real-time moderation events in your systems

1What webhooks do

Instead of polling the API, you register a URL and Telm sends a signed HTTP POST to it whenever something happens in your group. That is how you get moderation events into your own systems — a dashboard, a data warehouse, an alerting channel — in real time.

You manage webhook endpoints from the dashboard or through the API: register a URL, choose which events to subscribe to, optionally limit them to specific groups, send a test ping, and read the recent delivery log.

2Why push beats polling

You could call the journal endpoint on a timer to find new events, but that adds latency, spends quota, and can miss the exact moment something happens. Webhooks flip the model: Telm tells you the instant an event fires, so your systems react in seconds.

Typical uses include mirroring bans into your own admin tools, alerting a team channel when a raid is detected, streaming detections into analytics, or triggering a workflow when a member joins or leaves.

• Real-time: you learn about an event as it happens, not on your next poll.
• Efficient: no repeated reads that eat into your daily quota.
• Complete: deliveries are retried, so a brief outage on your side does not lose events.

3Events you can subscribe to

There are seven subscribable event types, covering spam verdicts, punishments and membership changes. A single moderated message can produce more than one event — a spam message that ends in a ban emits both spam.detected and user.banned.

• spam.detected — the engine flagged a message as spam.
• message.suspicious — a shadow (monitoring-mode) detection with a score.
• user.banned — a member was banned.
• user.kicked — a member was removed.
• user.muted — a member was muted.
• user.joined — a member joined the group.
• user.left — a member left the group.

4The payload envelope

Every delivery is a JSON envelope with a small, stable set of top-level fields and an event-specific data object inside. You can route on the type and time without parsing the details until you need them.

• id — a unique delivery id; redeliveries of the same event reuse the same id, which is how you deduplicate.
• type — the event type, one of the seven above.
• created_at — when the event fired, in RFC3339 UTC.
• group_id — the group the event belongs to (when applicable).
• data — an event-specific object: message and verdict details for spam events, member details for membership events.

5Verifying deliveries are really from Telm

Every delivery is signed so your server can confirm the request genuinely came from Telm and was not tampered with in transit. Validate the signature before you trust the payload, and reject anything that does not match.

The signature is an HMAC-SHA256 of the timestamp and the raw request body, keyed with your endpoint signing secret. To verify, recompute the HMAC over the timestamp header and the exact bytes you received, and compare it to the signature header.

• X-Telm-Signature — the signature, formatted as v1 followed by the hex HMAC-SHA256 of the timestamp joined to the body.
• X-Telm-Timestamp — the unix-seconds timestamp that is signed, so you can reject stale or replayed deliveries.
• X-Telm-Event — the event type, and X-Telm-Delivery — the delivery id for deduplication.
• The signing secret is shown once when you create the endpoint and starts with whsec_. Store it securely; it is the only thing that proves a delivery is genuine.

6Reliable, deduplicated delivery

Delivery is at-least-once: Telm makes sure an event reaches you, which means the same event can occasionally arrive twice. Because every redelivery reuses the same delivery id, you deduplicate by storing the ids you have processed and skipping repeats.

If your endpoint is unreachable or returns an error, the delivery is retried on a fixed schedule — the first delivery is immediate, with retries after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours — six attempts in total over about eight and a half hours. An endpoint that keeps failing is automatically disabled to protect both sides, and the owner is notified.

• Respond quickly with a 2xx status; do heavy work asynchronously after acknowledging.
• Deduplicate on the delivery id — never on the payload contents.
• An endpoint that fails about twenty times in a row with no success inside a 72-hour window is auto-disabled; re-enable it once your server is healthy.

7Managing endpoints and reading the log

You register, edit and remove webhook endpoints through the API. When you create one you receive the signing secret exactly once, choose the events to subscribe to, and optionally scope it to specific groups. A test call sends a signed ping so you can confirm your verification works before real traffic begins.

Each endpoint keeps a delivery log you can read back to see what was sent, when, and whether it succeeded — handy for debugging a receiver without waiting for the next live event.

• Create an endpoint and copy the whsec_ secret immediately.
• Send a test ping to validate your signature check end to end.
• Scope an endpoint to one group or leave it open to all groups you administer.
• Read the delivery log to inspect recent attempts and their outcomes.

8Best practices and common mistakes

A reliable receiver follows a few rules that prevent the most common problems.

• Verify the signature over the raw body bytes — parsing to JSON first and re-serialising can change the bytes and break the check.
• Return 2xx fast and process later; a slow handler causes timeouts and needless retries.
• Make handling idempotent so a redelivered event does not double-count.
• Use HTTPS on a publicly reachable URL; Telm blocks internal and private addresses and does not follow redirects.
• Keep the whsec_ secret out of logs and client code.