EventSub

EventSub is Twitch’s webhook protocol. When a stream goes live, Twitch posts to a callback URL you registered. ReplayVOD uses these subscriptions:

• stream.online — drives live indicators and triggers recordings.
• stream.offline — finalises recordings.
• channel.update — feeds title tracking in direct and relay server modes.

If your recorder can’t be reached over public HTTPS, see the Connect relay instead.

Requirements

• A publicly reachable HTTPS URL pointing at the recorder’s /api/v1/webhook/callback.
• A valid TLS certificate. Twitch refuses self-signed.
• An EventSub HMAC secret shared between the recorder and Twitch. The recorder generates one on first run and stores it in the database; no configuration needed.

Configure

Use System → EventSub in the owner dashboard, or set a complete env config. Env config wins over the dashboard when both exist.

Dashboard changes are saved as the desired server mode config. If the dashboard shows a restart is required, the current server keeps using the mode it booted with until you restart it.

For direct env setup:

SERVER_MODE=direct
WEBHOOK_CALLBACK_URL=https://your-domain.example/api/v1/webhook/callback

For Compose deployments, PUBLIC_BASE_URL still configures OAuth/frontend URLs; direct EventSub also needs its callback set explicitly:

PUBLIC_BASE_URL=https://your-domain.example
SERVER_MODE=direct
WEBHOOK_CALLBACK_URL=https://your-domain.example/api/v1/webhook/callback

No subscription IDs go in the config. The recorder creates and manages subscriptions itself, and reconciles them on every start.

Boot reconcile

On each start, the recorder:

1. Lists current EventSub subscriptions for its app.
2. Deletes orphaned subscriptions (channels you no longer follow, or stale entries from a previous process crash).
3. Creates missing subscriptions for the current channel set.

This means it’s safe to add or remove followed channels at any time; the next restart reconciles. No manual subscription management is required.

Quotas

Twitch enforces an EventSub subscription quota per app. ReplayVOD tracks current usage in the System dashboard tab. If you bump the quota, the dashboard surfaces it.

Polling is available without a callback

Use SERVER_MODE=poll if you do not have a working public callback. ReplayVOD will poll Helix for live detection and title changes instead of creating EventSub subscriptions.

Verifying it works

After a restart, check the System tab:

• The EventSub block shows current subscription count.
• Each followed channel gets one stream.online and one stream.offline subscription.

You can also tail the recorder logs — webhook deliveries show up as eventsub.received events.