Lifecycle webhooks let your systems react to live stream activity the moment it happens—when a publisher connects, a viewer starts playback, or a recording completes. This guide shows how to enable Nighthawk’s webhook forwarding, what gets sent, how it interacts with ingest/playback controls, and the concrete delivery limitations you should design around.
For broader installation and configuration context, see /server-docs.
What Nighthawk forwards (and when)
Nighthawk can forward stream lifecycle events to an HTTP(S) endpoint you control. The implementation forwards the raw hook body it receives from the streaming runtime and includes an event header so your handler can branch logic by type.
- Forwarded body: The raw JSON sent by the streaming runtime for that event. Treat it as untrusted input and parse only what you expect.
- Event header: Each POST includes an X-Nighthawk-Event header naming the event (for example, publish/play/dvr paths handled internally). Use this to route inside your webhook service.
- Typical internal hooks that lead to forwards:
- Publish attempts (on_publish)
- Playback attempts (on_play)
- DVR/recording notifications (on_dvr)
Important: forwarding is fire-and-forget with a short timeout. If your endpoint is slow or unreachable, events may be lost. See “Delivery model and limitations.”
Enable and verify webhook forwarding
Prerequisites
- You run Nighthawk in an environment where you can set container environment variables.
- You have an HTTP(S) endpoint ready to receive JSON POSTs and respond quickly.
Steps
1) Set the webhook URL
- Set the environment variable for your container to an HTTP or HTTPS URL. Only http:// or https:// scheme values are accepted.
2) Restart Nighthawk
- Restart the container to apply the setting. On startup, Nighthawk will detect the URL and log that event forwarding is enabled to your endpoint.
3) Generate a test event
- Start a publish from your encoder (to trigger on_publish), attempt a viewer playback (to trigger on_play), or finalize a recording (to trigger on_dvr if you use DVR/recording). Your endpoint should receive JSON POSTs. Confirm that X-Nighthawk-Event is present and correctly identifies the event.
4) Keep responses fast
- Your handler should return a quick 2xx. Long work should be queued internally; Nighthawk doesn’t wait and doesn’t retry.
Verification checklist
- Container logs show that webhook forwarding is enabled to the exact URL you configured.
- Your receiver observes POSTs with Content-Type: application/json and the X-Nighthawk-Event header.
- Your receiver handles empty or unexpected fields safely and logs parsing errors.
Payloads and trust model
Because the implementation forwards the raw hook body from the runtime, you should:
- Treat all fields as untrusted input. Validate types, lengths, and expected patterns before use.
- Expect that publish and play events carry session context (such as client IPs and stream identifiers) that your handler can inspect. Do not assume exact keys beyond what you explicitly test in your environment.
- For recording/DVR events, be aware that the internal control plane applies guardrails before acting on file paths. Only paths under the recordings directory are accepted for upload, and filenames must match a restricted safe-character set. Your own webhook receiver should apply similar caution if you use any path-like fields downstream.
Delivery model and limitations
Nighthawk’s webhook delivery is intentionally simple:
- Fire-and-forget: The server posts the JSON to your endpoint asynchronously and does not wait for, or act on, the response.
- Short timeout: The HTTP client used for forwarding has a five-second timeout.
- No retries or backoff: If a call times out or fails, the event is not retried by Nighthawk.
What this means for your design:
- Assume events can be lost under network issues, DNS problems, or endpoint slowness. Build your automation to tolerate gaps (e.g., reconcile with API logs or player analytics) and avoid critical state transitions that depend on a single webhook arriving.
- Keep your endpoint close and fast. Place it on reliable hosting, return 2xx quickly, and push heavy work to an internal queue.
- Consider idempotency in your handler. Even though Nighthawk does not retry, upstream systems or your own routing may cause replays; safe, idempotent processing avoids double side effects.
How webhooks interact with ingest and playback controls
- Publish authentication (on_publish): The internal handler expects a POST with a valid JSON object for publish events; invalid requests are rejected with a 400 inside the local control plane. If you enable a publish password, the publish flow is validated before a stream proceeds, and related events will reflect those outcomes.
- Signed playback tokens (on_play): When you configure a playback secret, the runtime is adjusted so on_play fires for HLS sessions and tokens are validated per request. The supplied helper signs tokens with HMAC-SHA256 over stream key and expiry; your backend should align with that scheme and TTL. The on_play path also inspects the client IP; special-casing of loopback occurs only under specific internal conditions.
Advice for your webhook logic
- For publish-related events, treat denials as expected outcomes and instrument them separately from system failures.
- For playback-related events, consider logging token-expired vs token-invalid cases distinctly on your side so support can act quickly.
Recording and S3 upload interplay (if you use DVR/recording)
- When a recording completes, Nighthawk will only attempt an object-store upload if you have configured a bucket and credentials. Missing credentials disable upload.
- Before upload, the control plane accepts only recording paths inside the recordings directory and rejects unsafe file names.
- The uploader performs a signed PUT per attempt and retries up to three times on errors. If all attempts fail, the local file is kept. Local deletion happens only after a successful upload and only when you explicitly enable the delete-local setting.
Operational takeaways
- If you rely on your own webhook receiver for archive workflows, keep in mind that the platform’s own upload has bounded retries and intentional failure retention. Use your webhook to correlate and alert on stuck uploads and reconcile with your object storage after failure events.
Hardening patterns for reliable automation
- Keep handlers fast: respond 2xx within a few milliseconds; queue longer work.
- Restrict ingress: allowlist source networks or place your receiver behind a private network path if possible.
- Add a shared secret: include a hard-to-guess path or query secret on your endpoint and rotate it periodically.
- Log by event type: use the X-Nighthawk-Event header to partition logs and alerting.
- Reconcile periodically: schedule a lightweight job that cross-checks your system of record (e.g., stream state, recordings) against recent webhook-driven state to fill gaps.
Troubleshooting quick wins
- No events arriving: confirm the URL uses http(s), confirm the startup log shows forwarding enabled, and verify your endpoint returns a fast 2xx locally.
- Sporadic misses: check for five-second timeouts on your receiver, reduce handler latency, and verify DNS and TLS health.
- Unexpected payloads: log and inspect full JSON safely; adjust your parser for fields your deployment emits; never assume presence of optional fields.
Links for further reading: /server-docs.