to_http

Sends events as HTTP requests to a webhook or API endpoint.

to_http url:string, [method=string, body=record|string|blob, encode=string,
        headers=record, paginate=string, paginate_delay=duration,
        parallel=int, tls=record, connection_timeout=duration,
        max_retry_count=int, retry_delay=duration]

Description

The to_http operator sends each input event as an HTTP request to a webhook or API endpoint. By default, it JSON-encodes the entire event as the request body and sends it as a POST request.

The operator is fire-and-forget: non-success HTTP status codes do not cause pipeline errors.

`url: string`

URL to send the request to. This is an expression evaluated per event, so you can use field values to construct the URL dynamically.

`method = string (optional)`

One of the following HTTP methods to use:

get
head
post
put
del
connect
options
trace

Defaults to post.

`body = blob|record|string (optional)`

Body to send with the HTTP request.

If the value is a record, then the body is encoded according to the encode option and an appropriate Content-Type is set for the request.

If not specified, the entire input event is JSON-encoded as the request body.

`encode = string (optional)`

Specifies how to encode record bodies. Supported values:

json
form

Defaults to json.

`headers = record (optional)`

Record of headers to send with the request. This is an expression evaluated per event, so you can use field values.

`paginate = string (optional)`

The string "link" to automatically follow pagination links in the HTTP Link response header per RFC 8288. The operator parses Link headers and follows the rel=next relation to fetch the next page. Pagination stops when the response no longer contains a rel=next link or when a non-success status code is received.

`paginate_delay = duration (optional)`

The duration to wait between consecutive pagination requests.

Defaults to 0s.

`parallel = int (optional)`

Maximum number of requests that can be in progress at any time.

Defaults to 1.

`tls = record (optional)`

TLS configuration. Provide an empty record (tls={}) to enable TLS with defaults or set fields to customize it.

{
  skip_peer_verification: bool, // skip certificate verification.
  cacert: string,               // CA bundle to verify peers.
  certfile: string,             // client certificate to present.
  keyfile: string,              // private key for the client certificate.
  min_version: string,          // minimum TLS version (`"1.0"`, `"1.1"`, `"1.2"`, "1.3"`).
  ciphers: string,              // OpenSSL cipher list string.
  client_ca: string,            // CA to validate client certificates.
  require_client_cert,          // require clients to present a certificate.
}

The client_ca and require_client_cert options are only applied for operators that accept incoming client connections, and otherwise ignored.

Any value not specified in the record will either be picked up from the configuration or if not configured will not be used by the operator.

See the Node TLS Setup guide for more details.

`connection_timeout = duration (optional)`

Timeout for the connection.

Defaults to 5s.

`max_retry_count = int (optional)`

The maximum times to retry a failed request. Every request has its own retry count.

Defaults to 0.

`retry_delay = duration (optional)`

The duration to wait between each retry.

Defaults to 1s.

Examples

Send events to a webhook

Send each event as a JSON POST request:

from {message: "hello", severity: "info"}
to_http "https://example.com/webhook"

The entire event is JSON-encoded as the request body.

Use a custom body

Override the default body with a string:

from {foo: "bar"}
to_http "https://example.com/api", body="custom-payload"

Send form-encoded data

from {user: "alice"}
to_http "https://example.com/api",
  body={name: "alice", role: "admin"},
  encode="form"

Set a custom method and headers

from {foo: "bar"}
to_http "https://example.com/api",
  method="put",
  headers={"X-Custom": "value"}

Send events with TLS

from {data: "sensitive"}
to_http "https://secure.example.com/api",
  tls={skip_peer_verification: true}

Send requests in parallel

Increase throughput by sending multiple requests concurrently:

load_file "events.json"
read_json
to_http "https://example.com/ingest", parallel=4

to_http

Description

url: string

method = string (optional)

body = blob|record|string (optional)

encode = string (optional)

headers = record (optional)

paginate = string (optional)

paginate_delay = duration (optional)

parallel = int (optional)

tls = record (optional)

connection_timeout = duration (optional)

max_retry_count = int (optional)

retry_delay = duration (optional)