100ms Webhooks Skill

100ms (live video SDK) sends a JSON POST to your endpoint when something happens in a room: a peer joins or leaves, a session opens or closes, a recording or HLS stream starts or finishes.

100ms webhooks are not signed. Add a secret header to the webhook in the 100ms dashboard and enter it here. Your endpoint authenticates each request by comparing that header with the value you stored.

When to Use This Skill

• How do I receive 100ms webhooks?
• Does 100ms sign webhook payloads? (No: use a secret header)
• How do I check the secret header on a 100ms webhook?
• How do I handle peer.join.success, session.close.success or recording.success events?
• Why does my 100ms webhook endpoint return 401?

Verification (core)

const crypto = require('crypto');

// Hash both sides: equal-length buffers, so timingSafeEqual never throws.
function safeEqual(received, expected) {
  const a = crypto.createHash('sha256').update(Buffer.from(received, 'latin1')).digest();
  const b = crypto.createHash('sha256').update(Buffer.from(expected, 'utf8')).digest();
  return crypto.timingSafeEqual(a, b);
}

function verify100msRequest(headers, secret = process.env.HUNDRED_MS_WEBHOOK_SECRET) {
  if (!secret) return false; // never accept when unconfigured
  const name = (process.env.HUNDRED_MS_WEBHOOK_HEADER || 'Authorization').toLowerCase();
  const received = headers[name]; // Node lowercases header names
  return typeof received === 'string' && received !== '' && safeEqual(received, secret);
}

• The header name is whatever you chose in the dashboard (HUNDRED_MS_WEBHOOK_HEADER, default Authorization), looked up case-insensitively.
• Compare the whole value (HUNDRED_MS_WEBHOOK_SECRET), including any Bearer prefix you typed. Do not strip or parse the prefix.
• Python: hmac.compare_digest on bytes (encode both sides; never pass str, which raises on non-ASCII).
• Return 401 for a missing header or mismatch, 400 for a body that isn't a JSON object with a type, and 200 once handled. 100ms retries three times on any other status.
• Read the body raw (express.raw({ type: '*/*' })) and authenticate before parsing it.
• A static shared credential authenticates the sender, not the body, and gives no replay protection (no signature, no timestamp). Use HTTPS and rotate the credential if it leaks. Optionally also allowlist the 100ms IP addresses (listed in their docs).

For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.

Event Types

The body is {version, id, app_id, account_id, template_id, timestamp, type, data}. type is <object>.<action>.<outcome>; dispatch on it and dedupe on id. The webhook must accept POST.

Environment Variables

HUNDRED_MS_WEBHOOK_HEADER=Authorization        # header name you chose (default: Authorization)
HUNDRED_MS_WEBHOOK_SECRET=your-secret-value    # exact, whole header value

The prefix is HUNDRED_MS because an environment variable name can't start with a digit.

Local Development

100ms can't reach localhost. Tunnel with the Hookdeck CLI (no account required):

npx hookdeck-cli listen 3000 100ms --path /webhooks/100ms

Use the printed URL as the webhook URL in the 100ms dashboard.

Resources

• references/overview.md - What 100ms webhooks are, events and payload shape
• references/setup.md - Configure the webhook and secret header in the dashboard
• references/verification.md - Secret header check details, gotchas, debugging 401s
• examples/ - Runnable Express, Next.js and FastAPI handlers with tests