Webhook output

The Webhook output forwards collected telemetry to any HTTP endpoint as JSON. It is Prelude Collector's most flexible Output and the right pick for custom integrations, event triggers, and forwarding to systems that are not natively supported. After the first mention this page refers to Prelude Collector as "the collector".

When to use

Pick Webhook when you need to push telemetry into an external system that speaks HTTP — a SIEM, a ticketing or automation platform, an internal API — and none of the dedicated Outputs fit. For high-volume, multi-consumer pipelines, Kafka is a better fit; for real-time streaming inside a Prelude deployment, prefer NATS. See Output selection.

How it works

Two delivery modes are available, controlled by the batch-mode field:

• Individual mode (batch-mode: false, default) — one HTTP request per record. Each request body is a single JSON object.
• Batch mode (batch-mode: true) — one HTTP request per collection cycle. The request body is a JSON array of all records in the batch.

The Content-Type header is always set to application/json.

Payload format

Each record is a JSON-serialised ParsedData envelope (kebab-case field names: device, device-id, model-name, path, key, timestamp, data-hash, data).

Individual mode

{
  "device": "router-01",
  "device-id": 42,
  "model-name": "cpu",
  "path": "Cisco-IOS-XR-wdsysmon-fd-oper:system-monitoring/cpu-utilization",
  "key": "cpu",
  "timestamp": "2024-01-01T12:00:00Z",
  "data-hash": "sha256:8f3c…",
  "data": {
    "usage": 45.2,
    "cores": 8
  }
}

Batch mode

[
  {
    "device": "router-01",
    "device-id": 42,
    "model-name": "cpu",
    "path": "Cisco-IOS-XR-wdsysmon-fd-oper:system-monitoring/cpu-utilization",
    "key": "cpu",
    "timestamp": "2024-01-01T12:00:00Z",
    "data-hash": "sha256:8f3c…",
    "data": { "usage": 45.2 }
  },
  {
    "device": "router-01",
    "device-id": 42,
    "model-name": "interface",
    "path": "openconfig-interfaces:interfaces/interface[name=GigabitEthernet0/0]/state",
    "key": "GigabitEthernet0/0",
    "timestamp": "2024-01-01T12:00:00Z",
    "data-hash": "sha256:5a91…",
    "data": { "in-octets": 123456 }
  }
]

Connection settings

Configure this backend through PUT /api/v1/outputs/webhook.

auth-header is stored encrypted. Sending "" or "********" on update preserves the existing value.

Authentication

Set auth-header to the full value of the HTTP Authorization header. The collector sends it verbatim on every request.

Additional custom headers (request signing, multi-tenant routing hints) can be added via the headers map.

Configuration example

{
  "enabled": true,
  "config": {
    "url": "https://hooks.example.com/prelude",
    "method": "POST",
    "auth-header": "Bearer <your-api-token>",
    "headers": {
      "X-Source": "prelude-collector"
    },
    "batch-mode": true,
    "timeout-ms": 5000
  }
}

Apply it with:

export BASE="https://collector.example.com"
export TOKEN="<your-api-token>"

curl -s -X PUT "$BASE/api/v1/outputs/webhook" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @webhook-output.json

Bruno: 08 Outputs / Update output config

Behavior on failure

Any HTTP response with status code 400 or higher is treated as a failure.

• In individual mode, failed records are counted and logged individually.
• In batch mode, a single failed HTTP request counts every record in the batch as failed.

There is no automatic retry — failed records are not re-queued. Track failure rates on /api/v1/outputs/metrics and alert on sustained increases. The request timeout defaults to 10 seconds and is configurable via timeout-ms.

To validate that the receiver is reachable, use POST /api/v1/outputs/webhook/detect, which sends an unauthenticated HEAD request to url (or to the saved URL when the body is omitted) and reports the response code.

Limitations

• The Content-Type header is fixed at application/json.
• There is no automatic retry, exponential backoff, or on-disk buffer — failed deliveries are dropped after one attempt.
• TLS verification follows the collector's system trust store; per- endpoint certificate pinning is not exposed here.
• HMAC request signing must be implemented on the receiving end using a secret carried in headers — the Output does not sign requests itself.

See also

• Output backends
• Output selection
• API reference