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>

Configuration

The following fields are used to define the device:

Device

Field	Required	Default	Description
id	Y		Unique 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	NumCPU	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 file name
tls.key_name	Y*	-	TLS private key file name

* Required when tls.status is true.

note

TLS certificate and key files must be placed in the service root directory.

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

The following are commonly used configuration types.

Basic

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

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

Token Authentication

Restricting access to named tokens...

devices: - 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...

devices: - 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...

devices: - 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...

devices: - 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