Webhooks

POST /woupi/webhook HTTP/1.1
Host: example.com
Content-Type: application/json
User-Agent: Woupi-EventSub/1
Woupi-Message-Id: 7d0c6f0e-2a4b-4f7e-8c1d-5b9a3e6f2d10
Woupi-Message-Timestamp: 2026-09-24T14:07:31.482Z
Woupi-Message-Signature: sha256=4f8a1c2e9b7d3f6a0e5c8b1d2f4a7e9c3b6d0f1a8e2c5b7d9f3a6c0e4b8d2f1a
Woupi-Message-Type: notification
Woupi-Message-Retry: 0
Woupi-Subscription-Type: channel.follow
Woupi-Subscription-Version: 1

{"subscription":{"id":"f1c2ae15-3b4d-4c9e-9a7b-0d8e6f5a4c31","type":"channel.follow","version":"1","status":"enabled","condition":{"broadcaster_user_id":"1042"},"transport":{"method":"webhook"},"created_at":"2026-09-24T14:05:12.000Z"},"event":{"broadcaster_user_id":"1042","broadcaster_user_login":"lunaplays","broadcaster_user_name":"LunaPlays","user_id":"3318","user_login":"max_quebec","user_name":"Max","followed_at":"2026-09-24T14:07:31.000Z"}}

signature = "sha256=" + hex( HMAC-SHA256( secret, message_id + timestamp + raw_body ) )

// npm install express
import crypto from 'node:crypto';
import express from 'express';

const SECRET = process.env.WOUPI_WEBHOOK_SECRET; // the secret sent when creating the subscription
const MAX_AGE_MS = 10 * 60 * 1000;
const seen = new Map(); // message id -> time seen (use Redis or a database table in production)

const app = express();

// Keep the raw bytes: the signature covers the exact body that was sent.
app.post('/woupi/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const id = req.get('Woupi-Message-Id') || '';
  const timestamp = req.get('Woupi-Message-Timestamp') || '';
  const signature = req.get('Woupi-Message-Signature') || '';
  const body = req.body; // Buffer

  const expected = 'sha256=' + crypto
    .createHmac('sha256', SECRET)
    .update(id + timestamp)
    .update(body)
    .digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.sendStatus(403);
  }

  const age = Date.now() - Date.parse(timestamp);
  if (!Number.isFinite(age) || Math.abs(age) > MAX_AGE_MS) {
    return res.sendStatus(403);
  }

  const message = JSON.parse(body.toString('utf8'));
  switch (req.get('Woupi-Message-Type')) {
    case 'webhook_callback_verification':
      return res.type('text/plain').send(message.challenge);
    case 'notification':
      if (seen.has(id)) return res.sendStatus(204); // already handled
      seen.set(id, Date.now());
      res.sendStatus(204); // acknowledge first, then do the work
      handleEvent(message.subscription.type, message.event);
      return;
    case 'revocation':
      console.warn('subscription revoked', message.subscription.id, message.subscription.status);
      return res.sendStatus(204);
    default:
      return res.sendStatus(400);
  }
});

function handleEvent(type, event) {
  if (event.is_test) console.log('(test event)');
  console.log(type, event);
}

// Forget message ids after 24 hours.
setInterval(() => {
  const limit = Date.now() - 24 * 60 * 60 * 1000;
  for (const [id, at] of seen) if (at < limit) seen.delete(id);
}, 60 * 60 * 1000);

app.listen(3000);

# pip install flask
import hashlib
import hmac
import os
import time
from datetime import datetime

from flask import Flask, request

SECRET = os.environ["WOUPI_WEBHOOK_SECRET"].encode()  # the secret sent when creating the subscription
MAX_AGE_S = 10 * 60
seen = {}  # message id -> time seen (use Redis or a database table in production)

app = Flask(__name__)


@app.post("/woupi/webhook")
def woupi_webhook():
    msg_id = request.headers.get("Woupi-Message-Id", "")
    timestamp = request.headers.get("Woupi-Message-Timestamp", "")
    signature = request.headers.get("Woupi-Message-Signature", "")
    body = request.get_data()  # raw bytes, before any JSON parsing

    digest = hmac.new(SECRET, (msg_id + timestamp).encode() + body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest("sha256=" + digest, signature):
        return "", 403

    try:
        sent_at = datetime.fromisoformat(timestamp.replace("Z", "+00:00")).timestamp()
    except ValueError:
        return "", 403
    if abs(time.time() - sent_at) > MAX_AGE_S:
        return "", 403

    message = request.get_json()
    kind = request.headers.get("Woupi-Message-Type")
    if kind == "webhook_callback_verification":
        return message["challenge"], 200, {"Content-Type": "text/plain"}
    if kind == "notification":
        if msg_id not in seen:  # skip messages already handled
            seen[msg_id] = time.time()
            handle_event(message["subscription"]["type"], message["event"])
        return "", 204
    if kind == "revocation":
        sub = message["subscription"]
        print("subscription revoked", sub["id"], sub["status"])
        return "", 204
    return "", 400


def handle_event(event_type, event):
    print(event_type, event)

{
  "subscription": {
    "id": "f1c2ae15-3b4d-4c9e-9a7b-0d8e6f5a4c31",
    "type": "channel.follow",
    "version": "1",
    "status": "webhook_callback_verification_pending",
    "condition": { "broadcaster_user_id": "1042" },
    "transport": { "method": "webhook" },
    "created_at": "2026-09-24T14:05:12.000Z"
  },
  "challenge": "hQ3v9K1xZ7mP2cR8tY5wL0nB4sD6fG1j"
}

HTTP/1.1 200 OK
Content-Type: text/plain

hQ3v9K1xZ7mP2cR8tY5wL0nB4sD6fG1j

{
  "subscription": {
    "id": "f1c2ae15-3b4d-4c9e-9a7b-0d8e6f5a4c31",
    "type": "channel.follow",
    "version": "1",
    "status": "notification_failures_exceeded",
    "condition": { "broadcaster_user_id": "1042" },
    "transport": { "method": "webhook" },
    "created_at": "2026-09-24T14:05:12.000Z"
  }
}