Splunk HEC

Synopsis

Creates an HTTP Event Collector listener that receives events from Splunk forwarders and HEC-compatible senders over HTTP or HTTPS.

Schema

- id: <numeric>
  name: <string>
  description: <string>
  type: splunkhec
  tags: <string[]>
  pipelines: <pipeline[]>
  status: <boolean>
  properties:
    port: <numeric>
    address: <string>
    tokens: <string[]>
    max_body_size: <numeric>
    enable_ack: <boolean>
    reuse: <boolean>
    workers: <numeric>
    tls:
      status: <boolean>
      cert_name: <string>
      key_name: <string>
      min_version: <string>
      insecure_skip_verify: <boolean>

Configuration

Device

Field	Required	Default	Description
id	Y	-	Unique numeric identifier
name	Y	-	Device name
description	N	-	Optional description
type	Y	-	Must be splunkhec
tags	N	-	Optional tags
pipelines	N	-	Optional pre-processor pipelines
status	N	true	Enable/disable the device

Connection

Field	Required	Default	Description
port	Y	-	TCP port to listen on
address	N	"0.0.0.0"	Network address to bind
tokens	N	-	Array of accepted HEC tokens; omit or leave empty for open access
max_body_size	N	26214400	Maximum decompressed request body size in bytes (default 25 MB)
enable_ack	N	false	Enable indexer acknowledgement support
reuse	N	true	Enable multi-worker mode
workers	N	CPU count	Number of worker processes when reuse is enabled

TLS

Field	Required	Default	Description
tls.status	N	false	Enable TLS encryption
tls.cert_name	Y*	-	TLS certificate. Accepts a file name (resolved relative to the service root directory) or inline PEM content (when the value starts with -----BEGIN).
tls.key_name	Y*	-	TLS private key. Same value semantics as tls.cert_name.
tls.min_version	N	-	Minimum accepted TLS version (e.g., 1.2, 1.3)
tls.insecure_skip_verify	N	false	Skip peer certificate verification

* = Required when tls.status is true.

Details

The device exposes the following HTTP endpoints on the configured port:

Endpoint	Method	Purpose
/services/collector	POST	JSON event submission
/services/collector/event	POST	JSON event submission (alternate)
/services/collector/raw	POST	Raw text line submission
/services/collector/raw/1.0	POST	Raw text line submission (versioned)
/services/collector/health	GET	Health check; no authentication required
/services/collector/health/1.0	GET	Health check (versioned); no authentication required
/services/collector/ack	POST	Indexer acknowledgement

The device validates the Authorization header using these schemes in order: Splunk <token>, Bearer <token>, bare token (no scheme prefix), and the ?token= query parameter as a fallback. When no tokens are configured, all requests are accepted without authentication. Health endpoints never require authentication.

Request bodies may be gzip-compressed (Content-Encoding: gzip). The max_body_size limit is enforced on the decompressed output, not on the compressed wire bytes, which prevents gzip-bomb payloads from expanding into memory unchecked.

The JSON event endpoints accept batched requests containing multiple concatenated JSON objects per body — a format that is standard HEC batch mode and is not valid single-document JSON. Each object must contain at least one of the fields event or fields at the top level; objects that fail this check return HEC error code 12.

The raw endpoint accepts plain text bodies. Each non-empty line is wrapped in a {"_raw":"..."} envelope. Per-request metadata fields (host, source, sourcetype, index) are read from query parameters and injected into every line envelope when present. When enable_ack is true, the raw endpoint also requires a channel identifier provided via the channel query parameter or the X-Splunk-Request-Channel header.

When enable_ack is true, the ACK endpoint echoes all submitted ack IDs back as confirmed (synthetic ACK). This unblocks senders that hold open connections waiting for ACK confirmation without requiring per-request state tracking. When enable_ack is false, the ACK endpoint remains registered and returns HEC error code 14 (ACK disabled) rather than a 404, matching expected Splunk behavior.

Examples

Basic

Creating a minimal HEC listener on port 8088 with open access...

- id: 1 name: basic_splunk_hec type: splunkhec properties: port: 8088

Token Authentication

Restricting access to named tokens...

- id: 2 name: secure_splunk_hec type: splunkhec properties: port: 8088 tokens: - "a8b3c1d2-e4f5-6789-abcd-ef0123456789" - "b9c4d3e5-f6a7-8901-bcde-f01234567890"

TLS

Enabling HTTPS with a TLS certificate and token authentication...

- id: 3 name: tls_splunk_hec type: splunkhec properties: port: 8088 tokens: - "a8b3c1d2-e4f5-6789-abcd-ef0123456789" tls: status: true cert_name: "hec.crt" key_name: "hec.key"

Acknowledgement

Enabling synthetic indexer acknowledgement for senders that require ACK confirmation...

- id: 4 name: ack_splunk_hec type: splunkhec properties: port: 8088 tokens: - "a8b3c1d2-e4f5-6789-abcd-ef0123456789" enable_ack: true

note

ACK IDs are always confirmed immediately. The device does not track per-event indexing state.

High-Volume

Tuning for high-throughput ingestion with increased body size limit and worker count...

- id: 5 name: highvol_splunk_hec type: splunkhec properties: port: 8088 tokens: - "a8b3c1d2-e4f5-6789-abcd-ef0123456789" max_body_size: 52428800 reuse: true workers: 8