HTTP

Synopsis

Creates an HTTP server that accepts messages via HTTP POST requests. Supports multiple authentication methods, TLS encryption, and customizable response handling.

Schema

- id: <numeric>
  name: <string>
  description: <string>
  type: http
  tags: <string[]>
  pipelines: <pipeline[]>
  status: <boolean>
  properties:
    protocol: <string>
    address: <string>
    port: <numeric>
    url: <string>
    content_type: <string>
    reuse: <boolean>
    workers: <numeric>
    response:
      code: <numeric>
      body: <string>
      content_type: <string>
    tls:
      status: <boolean>
      cert_name: <string>
      key_name: <string>
      min_version: <string>
      insecure_skip_verify: <boolean>
    authentication:
      type: <string>
      username: <string>
      password: <string>
    tokens:
      - token: <string>
        tenant_id: <string>
        expire_date: <numeric>
    header:
      key: <string>
      value: <string>
    hmac:
      type: <string>
      header: <string>
      key: <string>
      prefix: <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 http
tags	N	-	Optional tags
pipelines	N	-	Optional pre-processor pipelines
status	N	true	Enable/disable the device

Protocol

Field	Required	Default	Description
protocol	N	"tcp"	Transport protocol (typically tcp).
address	N	"0.0.0.0"	Listen address
port	Y		Listen port
url	N	"/"	URL path to listen on
content_type	N	"application/json"	Expected content type of incoming requests

Response

Field	Required	Default	Description
response.code	N	200	HTTP response status code
response.body	N	{"message":"success"}	Response body content
response.content_type	N	"application/json"	Response content type

Authentication

Field	Required	Default	Description
authentication.type	N	"none"	Authentication type (basic, bearer, header, or hmac)
authentication.username	Y*		Username for basic auth
authentication.password	Y*		Password for basic auth
tokens	Y*	-	Array of accepted bearer tokens. Each entry is a plain string or an object (see Multi-Tenancy).
header.key	Y*		Header name for header auth
header.value	Y*		Header value for header auth
hmac.type	Y*		HMAC algorithm (sha256 or sha512)
hmac.header	Y*		Header name for HMAC signature
hmac.key	Y*		Secret key for HMAC calculation
hmac.prefix	N	-	Optional prefix to strip from HMAC header value

* = Required when authentication.type is set to the corresponding method (tokens when it is bearer).

With bearer, the Authorization: Bearer <token> header (a bare token is also accepted) is matched against tokens. An empty tokens list rejects every request.

Multi-Tenancy

Loading include...

Requires authentication.type: bearer.

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	"1.2"	Minimum TLS version ("1.0", "1.1", "1.2", "1.3")
tls.insecure_skip_verify	N	false	Skip peer certificate verification. Use only for testing.

* = Required when tls.status is true.

Advanced Configuration

To enhance performance and achieve better message handling, the following settings are used.

Performance

Field	Required	Default	Description
reuse	N	true	Enable socket address reuse
workers	N	CPU count	Number of worker processes when reuse is enabled. Capped at the number of physical cores.

Loading include...

Examples

The following are commonly used configuration types.

Basic

Minimal HTTP listener on port 8080 accepting JSON POST requests at /logs:

Create a simple HTTP server...

devices: - id: 1 name: basic_http type: http properties: port: 8080 url: "/logs" content_type: "application/json" response: code: 200 body: '{"status":"ok"}'

Authentication

HTTP server with basic auth...

devices: - id: 2 name: auth_http type: http properties: port: 8080 url: "/api/logs" authentication: type: "basic" username: "vmetric" password: "P@ssw0rd"

API Keys

HTTP server using header-based API key authentication:

HTTP server with API key header auth...

devices: - id: 3 name: apikey_http type: http properties: port: 8080 url: "/api/v1/logs" authentication: type: "header" header: key: "X-API-Key" value: "${API_KEY}"

Multi-Tenant Bearer Tokens

A single endpoint serving multiple customers, each authenticating with its own bearer token. The matched token's tenant_id is attached to every record for downstream routing:

One HTTP listener accepting many tenants, one token each, one with an expiry...	devices: - id: 6 name: saas_http type: http properties: port: 8088 authentication: type: bearer tokens: - token: "acme-9f3c...key" tenant_id: "acme" expire_date: 1924905600 - token: "globex-7a1b...key" tenant_id: "globex"
A request bearing Acme's token is tagged with its tenant; the client IP is preserved...	{ "message": "{\"msg\":\"user login\"}", "_vmetric": { "device": { "id": 6, "name": "saas_http", "type": "http" }, "event": { "request": "198.51.100.20", "tenant_id": "acme" } } }

HMAC

HTTP server with SHA-256 HMAC signature verification:

HTTP server with HMAC signature verification...

devices: - id: 4 name: hmac_http type: http properties: port: 8080 url: "/secure/logs" authentication: type: "hmac" hmac: type: "sha256" header: "X-Signature" key: "${HMAC_SECRET}" prefix: "sha256="

warning

When using HMAC authentication, ensure that the client calculates the signature using the same algorithm and key.

Secure

HTTPS server with TLS and basic authentication...

devices: - id: 5 name: secure_http type: http properties: port: 8443 url: "/api/ingest" tls: status: true cert_name: "server.crt" key_name: "server.key" authentication: type: "basic" username: "ingest_user" password: "${INGEST_PASSWORD}" response: code: 201 body: '{"status":"created"}' content_type: "application/json"

warning

For production deployments, always use TLS encryption when authentication is enabled to protect credentials and tokens.