Event Webhooks¶

Flex Video can send outbound HTTP notifications when pipelines start or stop. Register a webhook subscriber, and the system will POST event payloads to your endpoint automatically.

How It Works¶

1. Register a webhook with a target URL and event types
2. Receive HTTP POST notifications when matching events occur
3. Unregister when you no longer need notifications

Webhooks use a fire-and-forget model:

• Notifications are sent asynchronously with a 5-second timeout
• No retries on failure -- if your endpoint is down, events are missed
• All matching subscribers are notified in parallel

Registration¶

Register a Webhook¶

curl -k -X POST https://<encoder-ip>:3539/flex/webhooks \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/hooks/pipeline",
    "events": ["pipeline.started", "pipeline.stopped"]
  }'

Response (201):

{
  "id": "wh_a1b2c3d4",
  "url": "https://your-server.com/hooks/pipeline",
  "events": ["pipeline.started", "pipeline.stopped"],
  "created_at": "2026-02-09T12:00:00Z"
}

List Webhooks¶

curl -k https://<encoder-ip>:3539/flex/webhooks

Response (200):

[
  {
    "id": "wh_a1b2c3d4",
    "url": "https://your-server.com/hooks/pipeline",
    "events": ["pipeline.started", "pipeline.stopped"],
    "created_at": "2026-02-09T12:00:00Z"
  }
]

Unregister a Webhook¶

curl -k -X DELETE https://<encoder-ip>:3539/flex/webhooks/wh_a1b2c3d4

Response: 204 No Content

Event Types¶

Outbound Authentication¶

To authenticate outbound webhook requests, include custom headers in the registration:

curl -k -X POST https://<encoder-ip>:3539/flex/webhooks \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/hooks/pipeline",
    "events": ["pipeline.started", "pipeline.stopped"],
    "headers": {
      "Authorization": "Bearer your-secret-token"
    }
  }'

Headers are write-only -- they are stored securely and included in outbound requests, but never returned in API responses (GET or POST).

You can include up to 10 custom headers with keys up to 128 characters and values up to 4,096 characters.

Event Payloads¶

pipeline.started¶

Sent when a pipeline reaches the playing state:

{
  "event": "pipeline.started",
  "timestamp": "2026-02-09T12:05:00Z",
  "pipeline": {
    "id": "camera-1",
    "name": "camera-1",
    "state": "playing",
    "output_url": "rtsp://192.168.1.100:8554/camera-1"
  }
}

pipeline.stopped¶

Sent when a pipeline is stopped. Includes the same pipeline details so subscribers can perform teardown (close firewall ports, unpublish streams, etc.):

{
  "event": "pipeline.stopped",
  "timestamp": "2026-02-09T12:10:00Z",
  "pipeline": {
    "id": "camera-1",
    "name": "camera-1",
    "state": "stopped",
    "output_url": "rtsp://192.168.1.100:8554/camera-1"
  }
}

Limits¶

A maximum of 50 webhooks can be registered at a time. Attempting to register beyond this limit returns 400 with error code WEBHOOK_LIMIT_REACHED. Unregister unused webhooks to free up slots.

Validation Rules¶

Error Handling¶

Webhooks are fire-and-forget. If your endpoint:

• Returns an error (4xx, 5xx): The error is logged, no retry
• Times out (>5 seconds): The connection is closed, no retry
• Is unreachable: The failure is logged, no retry

Subscribers that are consistently unreachable will not be automatically removed. Use DELETE /flex/webhooks/{id} to clean up stale registrations.

Best Practices¶

• Use HTTPS endpoints for webhook targets when possible
• Include authentication headers to verify that incoming requests are from your encoder
• Design your webhook handler to respond quickly (under 5 seconds)
• Use a message queue on your receiving end if processing takes longer
• Monitor your webhook endpoint availability to avoid missing events