Telegram moderation, programmable

Pass your key in the Authorization header (or X-API-Key):

Authorization: Bearer tk_live_...

• Keys are shown once at creation — store them like passwords.
• Read-only keys (scope read) can only perform GET requests.
• Revoking a key takes effect immediately.

Each delivery is an HTTPS POST with a JSON envelope:

{
  "id": "0d4f7a3e-...",        // unique event id — deduplicate by it
  "type": "spam.detected",
  "created_at": "2026-07-07T10:00:00Z",
  "group_id": -1001234567890,
  "data": {
    "message_id": 456,
    "user_id": 789,
    "text": "DM me for a deal!",
    "action": "deleted",
    "category": "contact_flow",
    "confidence": 0.92
  }
}

Deliveries are signed. Verify the X-Telm-Signature header (v1=hex(hmac_sha256(secret, timestamp + "." + body))) and reject stale timestamps:

# Python
import hmac, hashlib, time

def verify(secret: str, headers, body: bytes) -> bool:
    ts = int(headers["X-Telm-Timestamp"])
    if abs(time.time() - ts) > 300:          # 5 min anti-replay window
        return False
    expected = "v1=" + hmac.new(
        secret.encode(), f"{ts}.".encode() + body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, headers["X-Telm-Signature"])

// Node.js
import crypto from "node:crypto";

function verify(secret, headers, rawBody) {
  const ts = Number(headers["x-telm-timestamp"]);
  if (Math.abs(Date.now() / 1000 - ts) > 300) return false;
  const expected =
    "v1=" +
    crypto.createHmac("sha256", secret).update(`${ts}.`).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(headers["x-telm-signature"])
  );
}

• Respond with any 2xx within 10 seconds; redirects are not followed.
• Failed deliveries retry: +1m, +5m, +30m, +2h, +6h (6 attempts total).
• Delivery is at-least-once: deduplicate by the envelope id (also sent as X-Telm-Delivery). Event capture is best-effort — events emitted during brief maintenance windows on our side may be skipped, so treat webhooks as a real-time signal and use the journal API as the source of truth.
• The signature covers the timestamp and body only. Always read the event type from the signed type field in the body, not from the X-Telm-Event header.
• Endpoints failing for 3 days straight are disabled automatically — the owner gets a Telegram DM and can re-enable after fixing the receiver.