Webhook

The Webhook destination posts telemetry to an HTTP or HTTPS webhook endpoint. It sends log records to the configured URL using a chosen HTTP method and content type, with optional custom headers, TLS, and mTLS. This destination exports logs only.

Supported Telemetry

Metrics	Logs	Traces
✗	✓	✗

Prerequisites

You need a reachable webhook endpoint and any credentials it requires.

• A webhook server reachable from the collector, addressed by hostname or IP and port.
• The API path the server expects requests on, if any.
• Any authentication the endpoint requires, supplied as HTTP headers (for example an Authorization: Bearer <token> header) under Additional Headers.
• For HTTPS, a CA certificate if the server presents a certificate not trusted by the system store, and a client certificate and key if the server requires mutual TLS.

Configuration

Endpoint

Parameter	Type	Required	Default	Description
Scheme	Enum: http, https	No	https	The URL scheme used for the webhook requests.
Hostname	String	Yes	(empty)	Hostname or IP address of the webhook server.
Port	Integer	Yes	8080	Port of the webhook server. Range 1 to 65535.
Path	String	No	(empty)	API path to send webhook requests to.
HTTP Method	Enum: POST, PATCH, PUT	Yes	POST	The HTTP method used for the webhook requests.
Content Type	String	Yes	application/json	The Content-Type header for the webhook requests.
Payload Format	Enum: json_array, single	No	json_array	Payload format for log data. json_array sends all logs as a JSON array in a single request. single sends one HTTP request per log record.
Additional Headers	Map	No	(empty)	Additional HTTP headers to include in the webhook requests. Use this to supply authentication headers such as Authorization.

Advanced

Parameter	Type	Required	Default	Description
Request Timeout	Integer	No	5	Timeout for webhook requests, in seconds.

TLS (Advanced)

Applies when Scheme is https.

Parameter	Type	Required	Default	Description
Skip TLS Certificate Verification	Boolean	No	false	Skip TLS certificate verification.
TLS Certificate Authority File	String	No	(empty)	Certificate authority used to validate TLS certificates.
Mutual TLS	Boolean	No	false	Require client TLS authentication (mTLS).
TLS Client Certificate File	String	Yes (when Mutual TLS is enabled)	(empty)	TLS certificate used for client authentication when mutual TLS is enabled.
TLS Client Private Key File	String	Yes (when Mutual TLS is enabled)	(empty)	TLS private key used for client authentication when mutual TLS is enabled.

Retry on Failure (Advanced)

Parameter	Type	Required	Default	Description
Enable Retry on Failure	Boolean	No	true	Attempt to resend telemetry that has failed to transmit.
Initial interval	Integer	No	5	Time, in seconds, to wait after the first failure before retrying. Applies when retry is enabled.
Max interval	Integer	No	30	Upper bound, in seconds, on backoff. Applies when retry is enabled.
Max elapsed time	Integer	No	300	Maximum time, in seconds, spent trying to send a batch. Applies when retry is enabled.

Sending Queue (Advanced)

Parameter	Type	Required	Default	Description
Enable Sending Queue	Boolean	No	true	Buffer telemetry temporarily before sending to help avoid data loss during a temporary network outage.
Number of Consumers	Integer	No	10	Number of consumers that dequeue batches. Applies when the sending queue is enabled.
Queue Size	Integer	No	5000	Maximum size the queue can accept. Applies when the sending queue is enabled.
Enable Persistent Queuing	Boolean	No	true	Buffer telemetry to disk before sending to help avoid data loss during network outages or collector restarts. Applies when the sending queue is enabled.
Persistent Queue Storage	Extension	Yes	file_storage_persistent_queue	The storage used for the persistent queue. Applies when the sending queue and persistent queuing are enabled.

Examples

This destination sends logs over HTTPS to https://api.example.com:443/webhook using a bearer token for authentication. Each log record is sent as a single request.

apiVersion: bindplane.observiq.com/v1
kind: Destination
metadata:
  name: webhook
spec:
  type: webhook
  parameters:
    - name: scheme
      value: https
    - name: hostname
      value: api.example.com
    - name: port
      value: 443
    - name: path
      value: webhook
    - name: verb
      value: POST
    - name: content_type
      value: application/json
    - name: format
      value: single
    - name: headers
      value:
        Authorization: Bearer REPLACE_WITH_TOKEN

Configuration Tips

• Put authentication on the Additional Headers map. The webhook destination has no dedicated auth field, so credentials such as an API key or bearer token belong in a header like Authorization.
• Use json_array (the default) to batch logs into one request per export. Switch to single only when the endpoint expects one record per request, since single increases request volume.
• Leave the sending queue and persistent queuing enabled so a temporary network outage or a collector restart does not drop buffered logs.

Troubleshooting

Requests are rejected with 401 or 403

Symptoms: the endpoint returns an unauthorized or forbidden response and logs are not accepted.

Solutions:

1. Confirm the authentication header is present and correct under Additional Headers (for example Authorization).
2. Verify the token or credential has not expired and is authorized for the target path.

Connection or TLS failures

Symptoms: requests time out, connection is refused, or the TLS handshake fails.

Solutions:

1. Verify Hostname, Port, and Path match the endpoint, and that the collector can reach the server.
2. For HTTPS, supply a TLS Certificate Authority File if the server certificate is not in the system trust store. Enable Mutual TLS and provide the client certificate and key only if the server requires mTLS.
3. Increase Request Timeout if the endpoint is slow to respond.

Logs are delayed or dropped

Symptoms: records arrive late or are missing after the endpoint returns errors.

Solutions:

1. Keep Enable Retry on Failure on so transient non-2xx responses are retried with backoff.
2. Keep Enable Sending Queue and Enable Persistent Queuing on so buffered data survives outages and restarts.

Standalone Destination

apiVersion: bindplane.observiq.com/v1
kind: Destination
metadata:
  name: webhook
spec:
  type: webhook
  parameters:
    - name: scheme
      value: https
    - name: hostname
      value: api.example.com
    - name: port
      value: 443
    - name: path
      value: webhook
    - name: verb
      value: POST
    - name: content_type
      value: application/json
    - name: format
      value: json_array
    - name: headers
      value:
        Authorization: Bearer REPLACE_WITH_TOKEN

Related Resources

• Webhook Exporter (webhookexporter)