Webhooks

Signed event envelopes POSTed to your server - the catalog, how to verify them, and the operational warnings.

Add endpoints in Settings -> Developer (or the endpoints API) and TipPage POSTs an envelope when things happen:

{
  "id": "evt_9f1e2d3c4b5a6978",
  "type": "tip.created",
  "created": "2026-08-13T20:15:07.000Z",
  "actor": null,
  "data": { "...": "event-specific payload" }
}

URLs must be public https://. Delivery is at-least-once, unordered, retried with backoff for ~44 hours; an endpoint that keeps failing is disabled (you get a dashboard notification). Verify, answer 2xx fast, work async, and dedupe on id. The same events are on the realtime stream.

Payloads only carry what’s already visible on stream - never donor emails, payment ids, or pre-filter text.

actor

Who caused the event. null when the system did it (a payment landing, an overlay timing out).

user_id (u_...) is the person and never changes; platform_id is whichever linked account they used.

Verifying signatures

Anyone who finds your URL can POST a well-formed envelope to it. TipPage-Signature is the only proof a request came from TipPage - the other headers and the body are forgeable, and source IPs (Cloudflare’s) aren’t stable.

The MAC is HMAC-SHA256 of <t>.<raw body> with the endpoint’s whsec_ secret (shown once; rotate in the dashboard or the API).

import crypto from "node:crypto";

function verifyTipPageSignature(secret, header, rawBody, toleranceSec = 300) {
  const parts = Object.fromEntries((header || "").split(",").map((p) => p.split("=")));
  if (!parts.t || !parts.v1) return false;
  if (!(Math.abs(Date.now() / 1000 - Number(parts.t)) <= toleranceSec)) return false;
  const mac = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const got = Buffer.from(parts.v1, "hex");
  const want = Buffer.from(mac, "hex");
  return got.length === want.length && crypto.timingSafeEqual(got, want);
}

app.post("/webhooks/tippage", express.raw({ type: "*/*" }), (req, res) => {
  if (!verifyTipPageSignature(process.env.TIPPAGE_WHSEC, req.get("TipPage-Signature"), req.body)) {
    return res.status(401).end();
  }
  res.status(200).end();
  handleEvent(JSON.parse(req.body));
});

• Verify the raw bytes - re-serialized JSON won’t match.
• Keep the timestamp check, or a captured delivery can be replayed forever.
• Compare in constant time, not with ===.

Events

Subscribe each endpoint to the events you want, or *. Twitch and Kick alerts are separate events (twitch.*, kick.*) with the same shape; chat events are one event with platform. Every alert carries platform.

{
  "id": "evt_9f1e2d3c4b5a6978",
  "type": "tip.created",
  "created": "2026-08-13T20:15:07.000Z",
  "actor": null,
  "data": {
    "order_id": "tip_1755115200000_ab12cd",
    "name": "GigaChad42",
    "amount": 5.00,
    "message": "great stream!",
    "source": "stripe",
    "external_source": null,
    "external_ref": null,
    "is_paid": true,
    "is_replay": false,
    "is_sub_reward": false,
    "platform": "twitch",
    "platform_user_id": "123456789",
    "name_was_filtered": false,
    "message_was_filtered": false,
    "tts_url": null
  }
}

A few notes on specific events:

• twitch.channel_point_redemption fires for every reward, mapped or not. Dedupe on redemption_id. When is_managed is true (TipPage created the reward), close it with fulfill or cancel (refunds the points) under channel_points:manage; other rewards return 409 reward_not_managed, because Twitch only lets the creating app resolve them. Make a resolvable reward with POST /channel-points/rewards, or the streamer can use Create a new reward on the Channel points page.
• chat.command fires for your custom commands only, after permission and cooldown pass. command is the canonical name, invoked_as what was typed, args the rest of the line (null if none). Dedupe on message_id.

Warnings

warning goes to every endpoint and can’t be unsubscribed: your integration is probably doing something you didn’t mean. data is { code, message, ...extras }. Log or forward message; branch only on code, and treat unknown codes as a log line.

At most one of each per ~6 hours per streamer.

if (event.type === "warning") notifyDiscord(`TipPage: ${event.data.message}`);