On This Page

Home / Stream/ Administering· Notifications/ Notification Targets/Webhook Notification Targets

Webhook Notification Targets

With this option, you can send Cribl Stream Notifications to an arbitrary webhook. Select Webhook in the New Target modal to expose multiple left tabs, with the following configuration options:

General Settings
​

Target ID: Enter a unique ID used to identify the target. This will show in the Target ID column of the Targets tab. You can’t change it later, so make sure you like it.

Configuration
​

The added options that appear on this first left tab are:

URL: The endpoint that should receive Cribl Stream Notification events.

To proxy outbound HTTP/S requests, see System Proxy Configuration.

Method: Select the appropriate HTTP verb for requests: POST (the default), PUT, or PATCH.

Format: Specifies how to format Notification events before sending them to the endpoint. Select one of the following:

  • NDJSON (newline-delimited JSON, the default).
  • JSON Array.
  • Custom, which exposes these additional fields:
    • Source expression: JavaScript expression whose evaluation shapes the event that Cribl Stream sends to the endpoint – for example: notification=${_raw}. For other fields you can use, see Expression Fields. If empty, Cribl Stream will send the full notification event as stringified JSON.
    • Drop when null: Toggle to Yes if you want to drop events where the above Source expression evaluates to null.
    • Event delimiter: Delimiter string to insert between individual events. Defaults to newline character (\n).
    • Content type: Defaults to application/x‑ndjson. You can substitute a different content type for requests sent to the endpoint. This entry will be overridden by any content types set in this modal’s Advanced Settings tab > Extra HTTP Headers section.
    • Batch expression: Expression specifying how to format the payload for each batch. Defines a wrapper object in which to include the formatted events, such as a JSON document. This enables requests to APIs that require such objects. To reference the events to send, use the ${events} variable. An example expression to send the batch inside a JSON object would be: {"items" : [${events}] }.

Expression Fields
​

When building the Source expression, you can use the following fields:

Fields Common to All Notification Types
​

  • starttime: Beginning of the time bucket where this condition was reported. All Notifications have this field.
  • endtime: End of the time bucket where this condition was reported. All Notifications have this field.
  • _time: Timestamp when this Notification was created. All Notifications have this.
  • cribl_host: Hostname of the (physical or virtual) machine on which this Notification was created. All Destination and Source Notifications have this.
  • cribl_notification: Configured name/ID of this Notification. All Destination and Source Notifications have this.
  • origin_metadata: Object containing metadata about the Notification’s origin, with the following fields for all Destination Notifications:
    • type: “output”.
    • id: ID of the affected Destination.
    • subType: Destination’s type (where applicable).
  • origin_metadata: Object containing metadata about the Notification’s origin, with the following fields for all Source Notifications:
    • type: “input”.
    • id: ID of the affected Source.
    • subType: Source’s type (where applicable).

Unhealthy Destination
​

  • health: Numeric value where 0=green, 1=yellow, 2=red.
  • output: Output ID of the affected Destination.
  • _raw: “Destination ${output} [in group ${__worker_group}] is unhealthy”.
  • _metric: “health.outputs”.

Destination Persistent Queue Usage
​

  • output: Output ID of the affected Destination.
  • timeWindow: The interval at which notifications will be repeated.
  • usageThreshold: The minimum persistent queue utilization (stated as a percentage) that will trigger Notifications.
  • _metric: “system.pq_used”.
  • usage: The persistent queue utilization (stated as a percentage) that triggered the Notification.

Destination Backpressure Activated
​

  • backpressure_type: 1 for Block, 2 for Drop.
  • output: Output ID of the affected Destination.
  • _raw: “Backpressure ([dropping|blocking]) is engaged for destination ${output} [in group ${__worker_group}]”.
  • _metric: “backpressure.outputs”.

Source High Data Volume
​

  • health: Numeric value where 0=green, 1=yellow, 2=red.
  • bytes: Number of bytes received in the time bucket.
  • input: Input ID of the affected Source.
  • _raw: “Source ${input} [in group ${__worker_group}] traffic volume greater than ${dataVolume} in ${timeWindow}”.
  • _metric: “total.in_bytes”.

Source Low Data Volume
​

  • health: Numeric value where 0=green, 1=yellow, 2=red.
  • bytes: Number of bytes received in the time bucket.
  • input: Input ID of the affected Source.
  • _raw: “Source ${input} [in group ${__worker_group}] traffic volume less than ${dataVolume} in ${timeWindow}”.
  • _metric: “total.in_bytes”.

Source No Data Received
​

  • health: Numeric value where 0=green, 1=yellow, 2=red.
  • _time: Timestamp when this Notification was created.
  • input: Input ID of the affected Source.
  • _raw: “Source ${input} [in group ${__worker_group}] had no data for ${timeWindow}”.
  • _metric: “total.in_bytes”

License Expiration
​

  • severity: One of “warn” or “fatal”.
  • title: One of: “License expiring soon, data will stop flowing.” Or: “License has expired. Data flow has been stopped.”.
  • text: One of: “License will expire on ${expirationDate}, no external inputs will be read” after that time. Please contact sales@cribl.io to renew your license." Or: “License has expired.”

Authentication
​

Select one of the following options for authentication:

  • None: Don’t use authentication.
  • Auth token: Use HTTP token authentication. In the resulting Token field, enter the bearer token that must be included in the HTTP authorization header.
  • Basic: In the resulting Username and Password fields, enter HTTP Basic authentication credentials.

Post-Processing Settings
​

System fields: A list of fields to automatically add to events that use this output. By default, includes cribl_pipe (identifying the Cribl Stream Pipeline that processed the event). Supports wildcards. Other options include:

  • cribl_host – Cribl Stream Node that processed the event.
  • cribl_input – Cribl Stream Source that processed the event.
  • cribl_output – Cribl Stream Destination that processed the event.
  • cribl_route – Cribl Stream Route (or QuickConnect) that processed the event.
  • cribl_wp – Cribl Stream Worker Process that processed the event.

Retries
​

Honor Retry-After header: Whether to honor a Retry-After header, provided that the header specifies a delay no longer than 180 seconds. Cribl Stream limits the delay to 180 seconds even if the Retry-After header specifies a longer delay. When enabled, any Retry-After header received takes precedence over all other options configured in the Retries section. When disabled, all Retry-After headers are ignored.

Settings for failed HTTP requests: When you want to automatically retry requests that receive particular HTTP response status codes, use these settings to list those response codes.

For any HTTP response status codes that are not explicitly configured for retries, Cribl Stream applies the following rules:

Status CodeAction
Greater than or equal to 400 and less than or equal to 500.Drop the request.
Greater than 500.Retry the request.

Upon receiving a response code that’s on the list, Cribl Stream first waits for a set time interval called the Pre-backoff interval and then begins retrying the request. Time between retries increases based on an exponential backoff algorithm whose base is the Backoff multiplier, until the backoff multiplier reaches the Backoff limit (ms). At that point, Cribl Stream continues retrying the request without increasing the time between retries any further.

By default, this Destination has no response codes configured for automatic retries. For each response code you want to add to the list, click Add Setting and configure the following settings:

  • HTTP status code: A response code that indicates a failed request, for example 429 (Too Many Requests) or 503 (Service Unavailable).
  • Pre-backoff interval (ms): The amount of time to wait before beginning retries, in milliseconds. Defaults to 1000 (one second).
  • Backoff multiplier: The base for the exponential backoff algorithm. A value of 2 (the default) means that Cribl Stream will retry after 2 seconds, then 4 seconds, then 8 seconds, and so on.
  • Backoff limit (ms): The maximum backoff interval Cribl Stream should apply for its final retry, in milliseconds. Default (and minimum) is 10,000 (10 seconds); maximum is 180,000 (180 seconds, or 3 minutes).

Retry timed-out HTTP requests: When you want to automatically retry requests that have timed out, toggle this control on to display the following settings for configuring retry behavior:

  • Pre-backoff interval (ms): The amount of time to wait before beginning retries, in milliseconds. Defaults to 1000 (one second).
  • Backoff multiplier: The base for the exponential backoff algorithm. A value of 2 (the default) means that Cribl Stream will retry after 2 seconds, then 4 seconds, then 8 seconds, and so on.
  • Backoff limit (ms): The maximum backoff interval Cribl Stream should apply for its final retry, in milliseconds. Default (and minimum) is 10,000 (10 seconds); maximum is 180,000 (180 seconds, or 3 minutes).

Advanced Settings
​

Validate server certs: Reject certificates not authorized by a CA in the CA certificate path, nor by another trusted CA (for example, the system’s CA). Defaults to Yes.

Round-robin DNS: Toggle on to enable round-robin DNS lookup across multiple IP addresses, IPv4 and IPv6. When a DNS server resolves a Fully Qualified Domain Name (FQDN) to multiple IP addresses, Cribl Stream will sequentially use each address in the order they are returned by the DNS server for subsequent connection attempts.

Compress: Compresses the payload body before sending. Defaults to Yes (recommended).

Keep alive: By default, Cribl Stream sends Keep-Alive headers to the remote server and preserves the connection from the client side up to a maximum of 120 seconds. Toggle this off if you want Cribl Stream to close the connection immediately after sending a request.

Request timeout: Amount of time (in seconds) to wait for a request to complete before aborting it. Defaults to 30.

Request concurrency: Maximum number of concurrent requests per Worker Process. When Cribl Stream hits this limit, it begins throttling traffic to the downstream service. Defaults to 5. Minimum: 1. Maximum: 32.

Max body size (KB): Maximum size of the request body before compression. Defaults to 4096 KB, but you can set this limit to as high as 500 MB (512000 KB).

High values can cause high memory usage per Worker Node, especially if a dynamically constructed URL causes this target to send events to more than one URL. The actual request body size might exceed the specified value because the target adds bytes when it writes to the downstream receiver. Therefore, we recommend that you experiment with the Max body size value until downstream receivers reliably accept all events.

Max events per request: Maximum number of events to include in the request body. The 0 default allows unlimited events.

Flush period (sec): Maximum time between requests. Low values can cause the payload size to be smaller than its configured maximum. Defaults to 1.

Extra HTTP headers: Name-value pairs to pass to all events as additional HTTP headers. Values will be sent encrypted. You can also add headers dynamically on a per-event basis in the __headers field; headers added by this method take precedence over headers defined in the Extra HTTP headers table.

Failed request logging mode: Use this drop-down to determine which data should be logged when a request fails. Select among None (the default), Payload, or Payload + Headers. With this last option, Cribl Stream will redact all headers, except non-sensitive headers that you declare below in Safe headers.

Safe headers: Used to declare headers that are safe to log as plaintext. (Sensitive headers such as authorization will always be redacted, even if listed here.) Use a tab or hard return to separate header names.