React to changes with webhooks

Webhooks connect processing changes to your application. An administrator configures the destination in the dashboard. The independent webhook worker must be running to deliver events.

Prepare the receiver

1. Create an HTTPS endpoint in your backend.
2. Register it in the Orilla environment and keep its secret on the server.
3. Read the original request body before transforming it.
4. Verify the signature and delivery time.
5. Save the event ID to avoid processing it twice.

The SDK provides @orilla-video/sdk/webhooks to verify the Mux-Signature header against the original body. It accepts current and previous secrets to simplify rotation. See helper signatures and complete examples in packages/sdk/README.md and the package types.

Do not serialize the body again

The signature matches the received bytes. Running JSON.stringify() on an already parsed object can change those bytes and cause verification to fail.

Design for retries

A delivery can repeat or arrive after your application has already processed the change. Store the event ID with a unique constraint and apply effects idempotently.

Acknowledge a delivery after accepting it durably. If you delegate work to your own queue, save the event first and process it afterward.

Inspect deliveries

With the right permissions, you can review destinations and delivery history in the dashboard. In your own installation, run the webhook worker alongside the media processing worker.

For local development:

pnpm dev:webhooks

Production Compose includes its independent service. You can also retrieve a ready asset through the API; receiving an event does not replace authorization to access the resource.

History retention

The repository implementation expires ordinary webhook history after 90 days by default. Operators can change WEBHOOK_HISTORY_RETENTION_DAYS or set it to 0 to disable cleanup. Expired ordinary delivery IDs cannot be replayed. Pending retries, live delivery claims, recent replays and incident audit remain protected; expiring old attempts does not reset a delivery’s retry budget.

This retention increment is locally validated and awaits deployment. Receivers should retain their own durable event-ID deduplication records.

Incidents and other channels

The native events data.incident.opened, data.incident.closed, and data.incident.expired let you react to alerts. Select destinations explicitly in the rule or detector. Direct email, Slack, and PagerDuty channels have separate queues and auditing and do not replace webhook history IDs.