These docs are for Cribl Api 4.14 and are no longer actively maintained.
See the latest version (4.18).
Save Searches and Get Alerts
Use the Cribl API to save and schedule searches, then configure a Notification target and Notification so that you can receive alerts based on specific search results.
About the Example Requests
Replace the variables in the example requests with the corresponding information for your Cribl deployment.
In the cURL command options, replace
${token}with a valid API Bearer token. You can also set the$tokenenvironment variable to match the value of a Bearer token.You must commit and deploy the changes you make. You can use the Cribl API to automate commit and deploy commands.
Save a Search
To save a search, send a request to the POST /search/saved endpoint. The response is a JSON object with details about the saved search.
Saved searches are available to schedule to run at your desired interval.
curl --request POST \
--url 'https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/m/default_search/search/saved' \
--header 'Authorization: Bearer ${token}' \
--header 'Content-Type: application/json' \
--data '{
"name": "Goatherd Sample Dataset - Last Hour",
"id": "Goatherd_sample_dataset_last_hour",
"description": "Last hour, full sample rate",
"isPrivate": false,
"query": "cribl dataset=\"goatherd_sample_dataset\" | limit 1000",
"earliest": "-1h",
"latest": "now",
"sampleRate": 1
}'| Request Body Parameter | Description |
|---|---|
name (required) | Human-readable name for the search. In Cribl, Saved Searches lists the search by this name. |
id (required) | Unique ID for the saved search. You will need the id to schedule the saved search or otherwise update the saved search using the API. |
description (optional) | Human-readable description of the search. In Cribl, Saved Searches displays the description under the search name. |
isPrivate (optional) | Whether to keep the search’s result set private. Set to false to share the results with all Members. Set to true to ensure that only you can view the result set. |
query (required) | Query string to save, with escaped quotes around the Dataset name. In API requests, always begin the query with the cribl operator. The query must be a single line. See Build a Search for details about query syntax. |
earliest (optional) | Beginning of the query time range. |
latest (optional) | End of the query time range. |
sampleRate (optional) | Ratio to use to reduce the number of results returned. |
{
"items": [
{
"name": "Goatherd Sample Dataset - Last Hour",
"description": "Last hour, full sample rate",
"isPrivate": false,
"query": "cribl dataset=\"goatherd_sample_dataset\" | limit 1000",
"earliest": "-1h",
"latest": "now",
"sampleRate": 1,
"user": "google-oauth2|12345678910111EXAMPLE",
"displayUsername": "Alex Smith",
"id": "Goatherd_sample_dataset_last_hour"
}
],
"count": 1
}Schedule a Saved Search
Schedule an existing saved search by sending a request to PATCH /search/saved/{id}. The request URL uses the id value for an existing saved search to specify the search to schedule.
A PATCH /search/saved/{id} request updates the specified saved search to add a schedule object. If you want to maintain the unscheduled saved search, you can save and schedule the search in a single API request with POST /search/saved—just make sure to use a unique name and id in the request body.
The
PATCH /search/saved/{id}endpoint requires a complete representation of the search that you want to schedule in the request body. This endpoint does not support partial updates. Cribl removes any omitted fields when updating the search to include a schedule.Also, before you send the
PATCHrequest, confirm that the search configuration is correct. If the existing configuration is incorrect, the updated search may not function as expected. The response is a JSON object that includes details for the saved and scheduled search.
curl --request PATCH \
--url 'https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/m/default_search/search/saved/Goatherd_sample_dataset_last_hour' \
--header 'Authorization: Bearer ${token}' \
--header 'Content-Type: application/json' \
--data '{
"name": "Goatherd Sample Dataset - Last Hour",
"id": "Goatherd_sample_dataset_last_hour",
"description": "Last hour, full sample rate, scheduled once per hour",
"isPrivate": false,
"query": "cribl dataset=\"goatherd_sample_dataset\" | limit 1000",
"earliest": "-1h",
"latest": "now",
"sampleRate": 1,
"schedule": {
"enabled": true,
"cronSchedule": "0 * * * *",
"tz": "America/New_York",
"keepLastN": 4
}
}'This example maintains all the body parameters for the Goatherd_sample_dataset_last_hour saved search example and adds the following body parameters:
| Request Body Parameter | Description |
|---|---|
description (required) | Human-readable description of the search, updated to indicate that the search is scheduled. |
schedule.enabled (required) | Set to true so that the search runs according to the specified schedule. |
schedule.cronSchedule (required) | Custom cron expression that defines the schedule for the search. |
schedule.tz (required) | The IANA timezone to use for the schedule. |
schedule.keepLastN (optional) | Minimum number of result sets to store. |
{
"items": [
{
"name": "Goatherd Sample Dataset - Last Hour",
"description": "Last hour, full sample rate, scheduled once per hour",
"isPrivate": false,
"query": "cribl dataset=\"goatherd_sample_dataset\" | limit 1000",
"earliest": "-1h",
"latest": "now",
"sampleRate": 1,
"schedule": {
"enabled": true,
"cronSchedule": "0 * * * *",
"tz": "America/New_York",
"keepLastN": 4
},
"user": "google-oauth2|12345678910111EXAMPLE",
"displayUsername": "Alex Smith",
"id": "Goatherd_sample_dataset_last_hour"
}
],
"count": 1
}Create a Notification Target
To receive alerts when a scheduled search generates results that match the triggering conditions that you specify, you need a Notification target to send alerts to.
Once created, Notification targets are available across Cribl products. If you want to use the default System Messages target or an existing target, you can create a Notification without adding a new Notification target.
Amazon SNS Notification Target (Topic ARN)
This example creates an Amazon SNS Notification target for sending Notifications to an Amazon Simple Notification Service (SNS) topic. You can also configure Amazon SNS targets to send text messages (SMS) to a phone number.
The response is a JSON object that includes the Notification target configuration and a status object that lists the target’s health and metrics.
curl --request POST \
--url 'https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/m/notification-targets' \
--header 'Authorization: Bearer ${token}' \
--header 'Content-Type: application/json' \
--data '{
"id": "amazonsns_topicarn_hourly",
"type": "sns",
"destinationType": "topic",
"topicArn": "arn:aws:sns:us-east-1:123456789012:topicEXAMPLE",
"topicType": "fifo",
"messageGroupId": "https://host:port/myQueue-${C.vars.myVar}",
"region": "us-east-2",
"awsAuthenticationMethod": "auto",
"enableAssumeRole": true,
"assumeRoleArn": "arn:aws:iam::123456789012:role/roleEXAMPLE",
"assumeRoleExternalId": "externalId12345",
"durationSeconds": 3600,
"systemFields": [
"cribl_host",
"cribl_pipe"
],
"maxRetries": 2,
"endpoint": "https://sns.us-east-1.amazonaws.com",
"signatureVersion": "v4",
"reuseConnections": true,
"rejectUnauthorized": true,
"onBackPressure": "drop"
}'| Request Body Parameter | Description |
|---|---|
id (required) | A unique ID for the Notification target. Immutable. |
type (required) | The Notification target type (sns). |
destinationType (required) | Type of destination to use for the target (topic or phoneNumber). |
topicArn (required) | Amazon Resource Name (ARN) of the Amazon SNS topic to which you want to send Notifications. Use the format arn:aws:sns:region:account-id:MyTopic. |
topicType (optional) | Type of the topic selected in AWS SNS: fifo (default) or standard. Required for topic destination type. |
messageGroupId (optional) | The tag that specifies that a message belongs to a specific message group. Must be a JavaScript expression (which can evaluate to a constant value). Required for fifo topic type. |
region (required) | Region associated with the Amazon S3 bucket |
awsAuthenticationMethod (required) | AWS authentication method to use: auto (default) or manual. Specify auto to use IAM roles. If you specify manual, you must also provide an awsApiKey and awsSecretKey. |
awsApiKey (optional) | AWS access key. Required for manual authentication. |
awsSecretKey (optional) | AWS secret key. Required for manual authentication. |
enableAssumeRole (optional) | If true, specify an IAM role to use (assumeRoleArn) instead of automatically detecting one locally. |
assumeRoleArn (optional) | Amazon Resource Name (ARN) of the IAM role to assume. Required if enableAssumeRole is set to true. |
assumeRoleExternalId (optional) | External ID to use when assuming role. Required only when assuming a role that requires the external ID to delegate third-party access. |
durationSeconds (optional) | Duration of the assumed IAM role’s session, in seconds. Minimum is 900 (15 minutes), default is 3600 (1 hour), and maximum is 43200 (12 hours). |
systemFields (optional) | Fields to automatically add to Notification events to provide context before they are sent to the Notification target. |
maxRetries (optional) | Maximum number of retries before the output returns an error. Retries use an exponential backoff policy: a value of 2 means retry after 2 seconds, then 4 seconds, then 8 seconds, and so on. |
endpoint (optional) | SNS service endpoint. If empty, defaults to AWS Region-specific endpoint. |
signatureVersion (optional) | Signature version to use for signing SNS requests: v2 or v4 (default). |
reuseConnections (optional) | If true (default), reuse connections between requests. |
rejectUnauthorized (optional) | If true (default), reject certificates that cannot be verified against a valid Certificate Authority (for example, self-signed certificates). |
onBackpressure (optional) | How the Notificaton Target should handle events when the target exerts backpressure. - block: Block incoming events until backpressure is relieved- drop: Drop incoming events, which may result in data loss- queue: Queue events to disk until the target can accept them again |
{
"items": [
{
"id": "amazonsns_topicarn_hourly",
"type": "sns",
"destinationType": "topic",
"topicArn": "arn:aws:sns:us-east-1:123456789012:topicEXAMPLE",
"topicType": "fifo",
"messageGroupId": "https://host:port/myQueue-${C.vars.myVar}",
"region": "us-east-2",
"awsAuthenticationMethod": "auto",
"enableAssumeRole": true,
"assumeRoleArn": "arn:aws:iam::123456789012:role/roleEXAMPLE",
"assumeRoleExternalId": "externalId12345",
"durationSeconds": 3600,
"systemFields": [
"cribl_host",
"cribl_pipe"
],
"maxRetries": 2,
"endpoint": "https://sns.us-east-1.amazonaws.com",
"signatureVersion": "v4",
"reuseConnections": true,
"rejectUnauthorized": true,
"onBackpressure": "drop",
"status": {
"health": "Green",
"timestamp": 1757616403250,
"metrics": {
"totalSent": 0,
"errorCnt": 0
}
}
}
],
"count": 1
}Amazon SNS Notification Target (Phone Number)
This example creates an Amazon SNS Notification target for sending text message (SMS) Notifications to a phone number. You can also configure a target that uses the Amazon Simple Notification Service (SNS) topic instead.
The response is a JSON object that includes the Notification target configuration and a status object that lists the target’s health and metrics.
curl --request POST \
--url 'https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/m/notification-targets' \
--header 'Authorization: Bearer ${token}' \
--header 'Content-Type: application/json' \
--data '{
"id": "amazonsns_phone_hourly",
"type": "sns",
"destinationType": "phoneNumber",
"region": "us-east-2",
"phoneNumber": "+15555550123",
"allowlist": [
"+15555550***"
],
"awsAuthenticationMethod": "auto",
"enableAssumeRole": false,
"systemFields": [
"cribl_host",
"cribl_pipe"
],
"maxRetries": 2,
"endpoint": "https://sns.us-east-1.amazonaws.com",
"signatureVersion": "v4",
"reuseConnections": true,
"rejectUnauthorized": true,
"onBackpressure": "drop"
}'| Request Body Parameter | Description |
|---|---|
id (required) | A unique ID for the Notification target. Immutable. |
type (required) | The Notification target type (sns). |
destinationType (required) | Type of destination to use for the target (topic or phoneNumber). |
region (required) | Region associated with the Amazon S3 bucket |
phoneNumber (required) | Default phone number to use if the Notification event does not specify a __phoneNumber field. The phone number must be included in the allowlist. |
allowlist (required) | Wildcard-enabled list of phone numbers that are permitted to receive SMS Notifications. |
awsAuthenticationMethod (required) | AWS authentication method to use: auto (default) or manual. Specify auto to use IAM roles. If you specify manual, you must also provide an awsApiKey and awsSecretKey. |
awsApiKey (optional) | AWS access key. Required for manual authentication. |
awsSecretKey (optional) | AWS secret key. Required for manual authentication. |
enableAssumeRole (optional) | Set to false for phoneNumber destination type. |
systemFields (optional) | Fields to automatically add to Notification events to provide context before they are sent to the Notification target. |
maxRetries (optional) | Maximum number of retries before the output returns an error. Retries use an exponential backoff policy: a value of 2 means retry after 2 seconds, then 4 seconds, then 8 seconds, and so on. |
endpoint (optional) | SNS service endpoint. If empty, defaults to AWS Region-specific endpoint. |
signatureVersion (optional) | Signature version to use for signing SNS requests: v2 or v4 (default). |
reuseConnections (optional) | If true (default), reuse connections between requests. |
rejectUnauthorized (optional) | If true (default), reject certificates that cannot be verified against a valid Certificate Authority (for example, self-signed certificates). |
onBackpressure (optional) | How the Notificaton Target should handle events when the target exerts backpressure. - block: Block incoming events until backpressure is relieved- drop: Drop incoming events, which may result in data loss- queue: Queue events to disk until the target can accept them again |
{
"items": [
{
"id": "amazonsns_phone_hourly",
"type": "sns",
"destinationType": "phoneNumber",
"region": "us-east-2",
"phoneNumber": "+15555550123",
"allowlist": [
"+15555550***"
],
"awsAuthenticationMethod": "auto",
"enableAssumeRole": false,
"systemFields": [
"cribl_host",
"cribl_pipe"
],
"maxRetries": 2,
"endpoint": "https://sns.us-east-1.amazonaws.com",
"signatureVersion": "v4",
"reuseConnections": true,
"rejectUnauthorized": true,
"onBackpressure": "drop",
"status": {
"health": "Green",
"timestamp": 1757619679949,
"metrics": {
"totalSent": 0,
"errorCnt": 0
}
}
}
],
"count": 1
}Email Notification Target
This example creates an email Notification target that uses the SMTP server of your choice. The response is a JSON object that includes the Notification target configuration and a status object that lists the target’s health and metrics.
curl --request POST \
--url 'https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/m/notification-targets' \
--header 'Authorization: Bearer ${token}' \
--header 'Content-Type: application/json' \
--data '{
"id": "email_hourly",
"type": "smtp",
"host": "smtp.companydomain.com",
"port": 587,
"from": "notifications@companydomain.com",
"encryptionOption": "STARTTLS",
"tls": {
"rejectUnauthorized": true,
"minVersion": "TLSv1.2",
"maxVersion": "TLSv1.3"
},
"systemFields": [
"cribl_host",
"cribl_pipe"
],
"username": "notificationserviceacct",
"password": "serviceacctpassword",
"onBackpressure": "drop"
}'| Request Body Parameter | Description |
|---|---|
id (required) | A unique ID for the Notification target. Immutable. |
type (required) | The Notification target type (for email targets, smtp). |
host (required) | SMTP server hostname/DNS name or IP address. |
port (required) | SMTP port (typically set to 587 or 25). |
from (required) | Sender email address. |
encryptionOption (required) | Encryption type to secure SMTP communication. - STARTTLS: Start the connection as plain text, then upgrade to TLS encryption if the server supports it- STARTTLS_REQUIRED: Require TLS- TLS: Use an encrypted connection from the start without requiring a subsequent connection upgrade- NONE: Use a plain text connection |
tls.rejectUnauthorized (optional) | If true (default), reject certificates that cannot be verified against a valid Certificate Authority (for example, self-signed certificates). Do not include if you specify encryption option NONE. |
tls.minVersion (optional) | Minimum TLS version to use when connecting (TLSv1.2 or TLSv1.3). Do not include if you specify encryption option NONE. |
tls.maxVersion (optional) | Maximum TLS version to use when connecting (TLSv1.2 or TLSv1.3). Do not include if you specify encryption option NONE. |
systemFields (optional) | Fields to automatically add to Notification events to provide context before they are sent to the Notification target. |
username (optional) | Authentication principal (if required). |
password (optional) | Authentication credential (if required). |
onBackpressure (optional) | How the Notificaton Target should handle events when the target exerts backpressure. - block: Block incoming events until backpressure is relieved- drop: Drop incoming events, which may result in data loss- queue: Queue events to disk until the target can accept them again |
{
"items": [
{
"id": "email_hourly",
"type": "smtp",
"host": "smtp.companydomain.com",
"port": 587,
"from": "notifications@companydomain.com",
"encryptionOption": "STARTTLS",
"tls": {
"rejectUnauthorized": true,
"minVersion": "TLSv1.2",
"maxVersion": "TLSv1.3"
},
"systemFields": [
"cribl_host",
"cribl_pipe"
],
"username": "notificationserviceacct",
"password": "serviceacctpassword",
"onBackpressure": "drop",
"status": {
"health": "Green",
"timestamp": 1757620318311,
"metrics": {
"totalSent": 0,
"errorCnt": 0
}
}
}
],
"count": 1
}PagerDuty Notification Target
This example creates a PagerDuty Notification target that uses the Cribl Search native integration with the PagerDuty API. The response is a JSON object that includes the Notification target configuration and a status object that lists the target’s health and metrics.
curl --request POST \
--url 'https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/m/notification-targets' \
--header 'Authorization: Bearer ${token}' \
--header 'Content-Type: application/json' \
--data '{
"id": "pagerduty_hourly",
"type": "pager_duty",
"routingKey": "abc123def456ghi789jkl0123EXAMPLE",
"group": "ops",
"class": "infrastructure",
"component": "search",
"severity": "info",
"responseHonorRetryAfterHeader": true,
"responseRetrySettings": [
{
"httpStatus": 429,
"initialBackoff": 1000,
"backoffRate": 2,
"maxBackoff": 10000
},
{
"httpStatus": 503,
"initialBackoff": 1000,
"backoffRate": 2,
"maxBackoff": 10000
}
],
"timeoutRetrySettings": {
"timeoutRetry": true,
"initialBackoff": 1000,
"backoffRate": 2,
"maxBackoff": 10000
},
"systemFields": [
"cribl_host",
"cribl_pipe"
],
"onBackpressure": "queue"
}'| Request Body Parameter | Description |
|---|---|
id (required) | A unique ID for the Notification target. Immutable. |
type (required) | The Notification target type (pager_duty). |
routingKey (required) | Your 32-character Integration key on a PagerDuty service or global ruleset. |
group (optional) | PagerDuty default group to assign to Notifications. |
class (optional) | PagerDuty default class to assign to Notifications. |
component (optional) | PagerDuty default component value to assign to Notification events (default is logstream). |
severity (optional) | Default message severity for events sent to PagerDuty: info (default), error, warning, and critical. |
responseHonorRetryAfterHeader (optional) | Set to true to honor any Retry-After header that specifies a delay in seconds after the retry request (limited to 180 seconds). If false, ignore all Retry-After headers. |
responseRetrySettings.httpStatus (optional) | HTTP response status code that will trigger retries. This Notification target example is configured to retry for 429 and 503 HTTP response status codes. |
responseRetrySettings.initialBackoff (optional) | How long, in milliseconds, to wait before initiating backoff. Maximum is 600,000 ms (10 minutes). |
responseRetrySettings.backoffRate (optional) | Base for exponential backoff. A value of 2 (default) means retry after 2 seconds, then 4 seconds, then 8 seconds, and so on. |
responseRetrySettings.maxBackoff (optional) | Maximum backoff interval to apply, in milliseconds. Default and minimum is 10,000 ms (10 seconds); maximum is 180,000 ms (180 seconds). |
timeoutRetrySettings.timeoutRetry (optional) | Set to true to retry timed-out HTTP requests. |
timeoutRetrySettings.initialBackoff (optional) | How long, in milliseconds, to wait before initiating backoff for timeout retries. Maximum is 600,000 ms (10 minutes). |
timeoutRetrySettings.backoffRate (optional) | Base for exponential backoff for timeout retries. A value of 2 (default) means retry after 2 seconds, then 4 seconds, then 8 seconds, and so on. |
timeoutRetrySettings.maxBackoff (optional) | Maximum backoff interval to apply for timeout retries, in milliseconds. Default and minimum is 10,000 ms (10 seconds); maximum is 180,000 ms (180 seconds). |
systemFields (optional) | Fields to automatically add to Notification events to provide context before they are sent to the Notification target. |
onBackpressure (optional) | How the Notificaton Target should handle events when the target exerts backpressure. - block: Block incoming events until backpressure is relieved- drop: Drop incoming events, which may result in data loss- queue: Queue events to disk until the target can accept them again |
{
"items": [
{
"id": "pagerduty_hourly",
"type": "pager_duty",
"routingKey": "abc123def456ghi789jkl0123EXAMPLE",
"group": "ops",
"class": "infrastructure",
"component": "search",
"severity": "info",
"responseHonorRetryAfterHeader": true,
"responseRetrySettings": [
{
"httpStatus": 429,
"initialBackoff": 1000,
"backoffRate": 2,
"maxBackoff": 10000
},
{
"httpStatus": 503,
"initialBackoff": 1000,
"backoffRate": 2,
"maxBackoff": 10000
}
],
"timeoutRetrySettings": {
"timeoutRetry": true,
"initialBackoff": 1000,
"backoffRate": 2,
"maxBackoff": 10000
},
"systemFields": [
"cribl_host",
"cribl_pipe"
],
"onBackpressure": "drop",
"status": {
"health": "Green",
"timestamp": 1757620783602,
"metrics": {
"numBytesInBuffer": 0,
"numEventsInBuffer": 0,
"concurrentRequests": 0,
"lastFlushTime": 1757620783560,
"sentCount": 0,
"bytesOut": 0,
"numDropped": 0,
"parseErrorCount": 0,
"retryBufferCount": 0
}
}
}
],
"count": 1
}Slack Notification Target
This example creates a Slack Notification target that uses Slack’s incoming webhooks. The response is a JSON object that includes the Notification target configuration and a status object that lists the target’s health and metrics.
curl --request POST \
--url 'https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/m/notification-targets' \
--header 'Authorization: Bearer ${token}' \
--header 'Content-Type: application/json' \
--data '{
"id": "slack_hourly_webhook",
"type": "slack",
"url": "https://hooks.slack.com/services/12345678910/1234ABCD567/eFGH10987654321JkEXAMPLE",
"responseHonorRetryAfterHeader": true,
"responseRetrySettings": [
{
"httpStatus": 429,
"initialBackoff": 1000,
"backoffRate": 2,
"maxBackoff": 10000
},
{
"httpStatus": 503,
"initialBackoff": 1000,
"backoffRate": 2,
"maxBackoff": 10000
}
],
"timeoutRetrySettings": {
"timeoutRetry": true,
"initialBackoff": 1000,
"backoffRate": 2,
"maxBackoff": 10000
},
"systemFields": [
"cribl_host",
"cribl_pipe"
],
"onBackpressure": "drop"
}'| Request Body Parameter | Description |
|---|---|
id (required) | A unique ID for the Notification target. Immutable. |
type (required) | The Notification target type (slack). |
url (required) | The incoming webhook URL. |
responseHonorRetryAfterHeader (optional) | Set to true to honor any Retry-After header that specifies a delay in seconds after the retry request (limited to 180 seconds). If false, ignore all Retry-After headers. |
responseRetrySettings.httpStatus (optional) | HTTP response status code that will trigger retries. This Notification target example is configured to retry for 429 and 503 HTTP response status codes. |
responseRetrySettings.initialBackoff (optional) | How long, in milliseconds, to wait before initiating backoff. Maximum is 600,000 ms (10 minutes). |
responseRetrySettings.backoffRate (optional) | Base for exponential backoff. A value of 2 (default) means retry after 2 seconds, then 4 seconds, then 8 seconds, and so on. |
responseRetrySettings.maxBackoff (optional) | Maximum backoff interval to apply, in milliseconds. Default and minimum is 10,000 ms (10 seconds); maximum is 180,000 ms (180 seconds). |
timeoutRetrySettings.timeoutRetry (optional) | Set to true to retry timed-out HTTP requests. |
timeoutRetrySettings.initialBackoff (optional) | How long, in milliseconds, to wait before initiating backoff for timeout retries. Maximum is 600,000 ms (10 minutes). |
timeoutRetrySettings.backoffRate (optional) | Base for exponential backoff for timeout retries. A value of 2 (default) means retry after 2 seconds, then 4 seconds, then 8 seconds, and so on. |
timeoutRetrySettings.maxBackoff (optional) | Maximum backoff interval to apply for timeout retries, in milliseconds. Default and minimum is 10,000 ms (10 seconds); maximum is 180,000 ms (180 seconds). |
systemFields (optional) | Fields to automatically add to Notification events to provide context before they are sent to the Notification target. |
onBackpressure (optional) | How the Notificaton Target should handle events when the target exerts backpressure. - block: Block incoming events until backpressure is relieved- drop: Drop incoming events, which may result in data loss- queue: Queue events to disk until the target can accept them again |
{
"items": [
{
"id": "slack_hourly_webhook",
"type": "slack",
"url": "https://hooks.slack.com/services/12345678910/1234ABCD567/eFGH10987654321JkEXAMPLE",
"responseHonorRetryAfterHeader": true,
"responseRetrySettings": [
{
"httpStatus": 429,
"initialBackoff": 1000,
"backoffRate": 2,
"maxBackoff": 10000
},
{
"httpStatus": 503,
"initialBackoff": 1000,
"backoffRate": 2,
"maxBackoff": 10000
}
],
"timeoutRetrySettings": {
"timeoutRetry": true,
"initialBackoff": 1000,
"backoffRate": 2,
"maxBackoff": 10000
},
"systemFields": [
"cribl_host",
"cribl_pipe"
],
"onBackpressure": "drop",
"status": {
"health": "Green",
"timestamp": 1757621082705,
"metrics": {
"numBytesInBuffer": 0,
"numEventsInBuffer": 0,
"concurrentRequests": 0,
"lastFlushTime": 1757621082657,
"sentCount": 0,
"bytesOut": 0,
"numDropped": 0,
"parseErrorCount": 0,
"retryBufferCount": 0
}
}
}
],
"count": 1
}Webhook Notification Target
This example creates a webhook Notification target that applies a custom format to Notification events before sending them. The response is a JSON object that includes the Notification target configuration and a status object that lists the target’s health and metrics.
curl --request POST \
--url 'https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/m/notification-targets' \
--header 'Authorization: Bearer ${token}' \
--header 'Content-Type: application/json' \
--data '{
"id": "webhook_hourly",
"type": "webhook",
"url": "https://companydomain.com/api/webhooks/search-results",
"method": "POST",
"format": "custom",
"customSourceExpression": "__httpOut",
"customDropWhenNull": false,
"customEventDelimiter": "\n",
"customContentType": "application/x-ndjson",
"customPayloadExpression": "`${events}`",
"authType": "token",
"token": "4f3e2d1c9b8a7e6f5d4c3b2aEXAMPLE",
"systemFields": [
"cribl_host",
"cribl_pipe"
],
"responseHonorRetryAfterHeader": true,
"responseRetrySettings": [
{
"httpStatus": 429,
"initialBackoff": 1000,
"backoffRate": 2,
"maxBackoff": 10000
},
{
"httpStatus": 503,
"initialBackoff": 1000,
"backoffRate": 2,
"maxBackoff": 10000
}
],
"timeoutRetrySettings": {
"timeoutRetry": true,
"initialBackoff": 1000,
"backoffRate": 2,
"maxBackoff": 10000
},
"rejectUnauthorized": true,
"useRoundRobinDns": true,
"compress": true,
"keepAlive": true,
"timeoutSec": 30,
"concurrency": 5,
"maxPayloadSizeKB": 4096,
"maxPayloadEvents": 0,
"flushPeriodSec": 1,
"extraHttpHeaders": [
{
"name": "User-Agent",
"value": "Cribl Search"
}
],
"failedRequestLoggingMode": "payloadAndHeaders",
"safeHeaders": [
"User-Agent",
"Content-Type"
],
"onBackpressure": "drop"
}'| Request Body Parameter | Description |
|---|---|
id (required) | Unique ID for the Notification target. Immutable. |
type (required) | The Notification target type (webhook). |
url (required) | Endpoint that should receive Notification events. |
method (optional) | Method to use when sending Notification events: POST (default), PUT, or PATCH. |
format (optional) | Format to apply to Notification events before sending them to the endpoint: ndjson (default), json_array, custom, or advanced.If you specify custom, also include customSourceExpression, customDropWhenNull, customEventDelimiter, customContentType, and customPayloadExpression.If you specify advanced, also include advancedContentType, formatEventCode, and formatPayloadCode. |
customSourceExpression (optional) | JavaScript expression whose evaluation shapes the Notification event that is sent to the endpoint (for example, notification=${_raw}). If empty, Cribl sends the full Notification event as stringified JSON. |
customDropWhenNull (optional) | If true, Cribl drops events when customSourceExpression evaluates to null. Use for custom format. |
customEventDelimiter (optional) | Delimiter string to insert between individual events. Default is \n. Use for custom format. |
customContentType (optional) | Content type to use for the request. Default is application/x-ndjson. Any content types set in extraHttpHeaders will override this entry. Use for custom format. |
customPayloadExpression (optional) | Expression that specifies how to format the payload for each batch. Defines a wrapper object in which to include formatted events. To reference the events to send, use the ${events} variable (for example, {"items" : [${events}] }). Use for custom format. |
advancedContentType (optional) | Content type to use for the request. Default is application/json. Any content types set in extraHttpHeaders will override this entry. Use for advanced format. |
formatEventCode (optional) | Custom JavaScript code to format incoming event data accessible through the __e variable. The formatted content is added to (__e['__eventOut']) if available. Otherwise, the original event is serialized as JSON. **CAUTION: This function is evaluated in an unprotected context, allowing you to execute almost any JavaScript code.(()) Use for advanced format. |
formatPayloadCode (optional) | Optional JavaScript code to format the payload sent to the destination. The payload, containing a batch of formatted events, is accessible through the __e['payload'] variable. The formatted payload is returned in the __e['__payloadOut'] variable. CAUTION: This function is evaluated in an unprotected context, allowing you to execute almost any JavaScript code. Use for advanced format. |
authType (required) | Authentication type: none, token, or basic. |
token (optional) | Authentication token for token authentication type. |
username (optional) | Username for basic authentication type. |
password (optional) | Password for basic authentication type. |
systemFields (optional) | Fields to automatically add to Notification events to provide context before they are sent to the Notification target. |
responseHonorRetryAfterHeader (optional) | Set to true to honor any Retry-After header that specifies a delay in seconds after the retry request (limited to 180 seconds). If false, Cribl ignores all Retry-After headers. |
responseRetrySettings.httpStatus (optional) | HTTP response status code that will trigger retries. This Notification target example is configured to retry for 429 and 503 HTTP response status codes. |
responseRetrySettings.initialBackoff (optional) | How long, in milliseconds, to wait before initiating backoff. Maximum is 600,000 ms (10 minutes). |
responseRetrySettings.backoffRate (optional) | Base for exponential backoff. A value of 2 (default) means retry after 2 seconds, then 4 seconds, then 8 seconds, and so on. |
responseRetrySettings.maxBackoff (optional) | Maximum backoff interval to apply, in milliseconds. Default and minimum is 10,000 ms (10 seconds); maximum is 180,000 ms (180 seconds). |
timeoutRetrySettings.timeoutRetry (optional) | Set to true to retry timed-out HTTP requests. |
timeoutRetrySettings.initialBackoff (optional) | How long, in milliseconds, to wait before initiating backoff for timeout retries. Maximum is 600,000 ms (10 minutes). |
timeoutRetrySettings.backoffRate (optional) | Base for exponential backoff for timeout retries. A value of 2 (default) means retry after 2 seconds, then 4 seconds, then 8 seconds, and so on. |
timeoutRetrySettings.maxBackoff (optional) | Maximum backoff interval to apply for timeout retries, in milliseconds. Default and minimum is 10,000 ms (10 seconds); maximum is 180,000 ms (180 seconds). |
rejectUnauthorized (optional) | If true (default), reject certificates that cannot be verified against a valid Certificate Authority (for example, self-signed certificates). |
useRoundRobinDns (optional) | If true, when a DNS server returns multiple addresses, Search will cycle through them in the order returned. Otherwise, false (default). |
compress (optional) | If true (defualt), Cribl compresses the payload body before sending. |
keepAlive (optional) | If true (default), send Keep-Alive headers to the remote server and preserves the connection from the client side for a maximum of 120 seconds. If false, close the connection immediately after sending a request. |
timeoutSec (optional) | Amount of time, in seconds, to wait for a request to complete before canceling it. Default is 30. |
concurrency (optional) | Maximum number of ongoing requests before blocking. Default is 5. |
maxPayloadSizeKB (optional) | Maximum size, in KB, of the request body before compression. Default is 4096. |
maxPayloadEvents (optional) | Maximum number of events to include in the request body. Default is 0 (unlimited). |
flushPeriodSec (optional) | Maximum time between requests. Default is 1. Low values can cause the payload size to be smaller than the maxPayloadSizeKB. |
extraHttpHeaders (optional) | Name-value pairs to pass to all Notification events as additional HTTP headers. Values are sent encrypted. Headers added dynamically on a per-event basis in the __headers take precedence over headers defined in extraHttpHeaders. |
failedRequestLoggingMode (optional) | Data to log when a request fails: none (default), payload, or payloadAndHeaders. All headers are redacted unless listed in safeHeaders. |
safeHeaders (optional) | List of headers that are safe to log in plain text. |
onBackpressure (optional) | How the Notificaton Target should handle events when the target exerts backpressure. - block: Block incoming events until backpressure is relieved- drop: Drop incoming events, which may result in data loss- queue: Queue events to disk until the target can accept them again |
{
"items": [
{
"id": "webhook_hourly",
"type": "webhook",
"url": "https://companydomain.com/api/webhooks/search-results",
"method": "POST",
"format": "custom",
"customSourceExpression": "__httpOut",
"customDropWhenNull": false,
"customEventDelimiter": "\n",
"customContentType": "application/x-ndjson",
"customPayloadExpression": "`${events}`",
"authType": "token",
"token": "4f3e2d1c9b8a7e6f5d4c3b2aEXAMPLE",
"systemFields": [
"cribl_host",
"cribl_pipe"
],
"responseHonorRetryAfterHeader": true,
"responseRetrySettings": [
{
"httpStatus": 429,
"initialBackoff": 1000,
"backoffRate": 2,
"maxBackoff": 10000
},
{
"httpStatus": 503,
"initialBackoff": 1000,
"backoffRate": 2,
"maxBackoff": 10000
}
],
"timeoutRetrySettings": {
"timeoutRetry": true,
"initialBackoff": 1000,
"backoffRate": 2,
"maxBackoff": 10000
},
"rejectUnauthorized": true,
"useRoundRobinDns": true,
"compress": true,
"keepAlive": true,
"timeoutSec": 30,
"concurrency": 5,
"maxPayloadSizeKB": 4096,
"maxPayloadEvents": 0,
"flushPeriodSec": 1,
"extraHttpHeaders": [
{
"name": "User-Agent",
"value": "Cribl Search"
}
],
"failedRequestLoggingMode": "payloadAndHeaders",
"safeHeaders": [
"User-Agent",
"Content-Type"
],
"onBackpressure": "drop",
"status": {
"health": "Green",
"timestamp": 1757685442252,
"metrics": {
"numBytesInBuffer": 0,
"numEventsInBuffer": 0,
"concurrentRequests": 0,
"lastFlushTime": 1757685441987,
"sentCount": 0,
"bytesOut": 0,
"numDropped": 0,
"parseErrorCount": 0,
"retryBufferCount": 0,
"numBatches": 0
}
}
}
],
"count": 1
}Create a Notification to Send Alerts
Create a Notification to get alerts when a scheduled search generates results that match the triggering conditions that you specify.
When you create a Notification, Cribl also adds the Notification details to the search that you specified for savedQueryId. If you retrieve the saved search, its configuration will include the schedule and Notification details.
You must have a saved and scheduled search and a Notification target to create a Notification.
Cribl does not support creating Notification events for searches that reside within Packs.
The following example demonstrates how to create a Notification for a scheduled search based on a custom condition. The response is a JSON object that includes the Notification configuration.
curl --request GET \
--url 'https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/m/default_search/notifications' \
--header 'Authorization: Bearer ${token}' \
--header 'Content-Type: application/json' \
--data '{
"id": "goatherd_mexico_city",
"disabled": false,
"condition": "search",
"targets": [
"slack_hourly_webhook"
],
"conf": {
"triggerType": "custom",
"savedQueryId": "Goatherd_sample_dataset_last_hour",
"trigger": "location=\"Mexico City\"",
"message": "Date: {{timestamp}}\n\nA notification was triggered for the scheduled search: {{searchId}},\nTenant ID: {{tenantId}}\nSearch ID: {{savedQueryId}}.\nNotification: {{notificationId}}"
},
"targetConfigs": [
{
"id": "slack_hourly_webhook",
"conf": {
"includeResults": true,
"attachmentType": "inline"
}
}
],
"metadata": [
{
"name": "team",
"value": "dataops"
},
{
"name": "location",
"value": "mexico_city"
},
{
"name": "alert_type",
"value": "location_match"
}
]
}'| Request Body Parameter | Description |
|---|---|
id (required) | Unique ID for the Notification. Immutable. |
disabled (required) | Set to false to send alerts according to the Notification. |
condition (required) | Event or state that triggers the Notification. For search Notifications, the value is search. |
targets (required) | Notification targets to use. All Notifications, regardless of their configured target, also generate a message in the Cribl Search UI. |
conf.triggerType (optional) | Type of trigger, custom (default) or resultsCount. |
conf.savedQueryId (required) | The id for the saved and scheduled search associated with the Notification. |
conf.trigger (required) | Kusto expression for the custom Notification trigger. |
conf.message (optional) | Message payload template. Maximum is 1000 characters. |
targetConfigs.id (optional) | The id of the target to add configuration for (if you want to include additional configuration for each target listed in the targets array). |
targetConfigs.conf.includeResults (optional) | If true, insert the {{resultSet}} template variable into Notification events for the target. |
targetConfigs.conf.attachmentType (optional) | How results are displayed in the Notification events for the target. For Slack Notification targets, the attachmentType is inline. |
metadata (optional) | Name-value pairs that provide context, enrich Notification payloads, and facilitate filtering or routing. |
{
"items": [
{
"disabled": false,
"condition": "search",
"targets": [
"slack_hourly_webhook"
],
"conf": {
"triggerType": "custom",
"savedQueryId": "Goatherd_sample_dataset_last_hour",
"trigger": "location=\"Mexico City\"",
"message": "Date: {{timestamp}}\n\nA notification was triggered for the scheduled search: {{searchId}},\nTenant ID: {{tenantId}}\nSearch ID: {{savedQueryId}}.\nNotification: {{notificationId}}"
},
"targetConfigs": [
{
"id": "slack_hourly_webhook",
"conf": {
"includeResults": true,
"attachmentType": "inline"
}
}
],
"metadata": [
{
"name": "team",
"value": "dataops"
},
{
"name": "location",
"value": "mexico_city"
},
{
"name": "'alert_type'",
"value": "location_match"
}
],
"group": "default_search",
"id": "goatherd_mexico_city"
}
],
"count": 1
}The following example demonstrates how to create a Notification for a scheduled search based on search results.
curl --request GET \
--url 'https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/m/default_search/notifications' \
--header 'Authorization: Bearer ${token}' \
--header 'Content-Type: application/json' \
--data '{
"id": "goatherd_results_burst",
"disabled": false,
"condition": "search",
"targets": [
"slack_hourly_webhook"
],
"conf": {
"triggerType": "resultsCount",
"savedQueryId": "Goatherd_sample_dataset_last_hour",
"triggerComparator": ">=",
"triggerCount": 10,
"message": "Date: {{timestamp}}\n\nA notification was triggered for the scheduled search: {{searchId}},\nTenant ID: {{tenantId}}\nSearch ID: {{savedQueryId}}.\nNotification: {{notificationId}}"
},
"targetConfigs": [
{
"id": "slack_hourly_webhook",
"conf": {
"includeResults": true,
"attachmentType": "inline"
}
}
],
"metadata": [
{
"name": "team",
"value": "dataops"
},
{
"name": "alert_type",
"value": "results_10_plus"
}
]
}'| Request Body Parameter | Description |
|---|---|
id (required) | Unique ID for the Notification. Immutable. |
disabled (required) | Set to false to send alerts according to the Notification. |
condition (required) | Event or state that triggers the Notification. For search Notifications, the value is search. |
targets (required) | Notification targets to use. All Notifications, regardless of their configured target, also generate a message in the Cribl Search UI. |
conf.triggerType (optional) | Type of trigger, custom (default) or resultsCount. |
conf.savedQueryId (required) | The id for the saved and scheduled search associated with the Notification. |
conf.triggerComparator (required) | Comparison operator to use for the Notification trigger. |
conf.triggerCount (required) | Numeric threshold to compare against the result count. |
conf.message (optional) | Message payload template. Maximum is 1000 characters. |
targetConfigs.id (optional) | The id of the target to add configuration for (if you want to include additional configuration for each target listed in the targets array). |
targetConfigs.conf.includeResults (optional) | If true, insert the {{resultSet}} template variable into Notification events for the target. |
targetConfigs.conf.attachmentType (optional) | How results are displayed in the Notification events for the target. For Slack Notification targets, the attachmentType is inline. |
metadata (optional) | Name-value pairs that provide context, enrich Notification payloads, and facilitate filtering or routing. |
{
"items": [
{
"disabled": false,
"condition": "search",
"targets": [
"slack_hourly_webhook"
],
"conf": {
"triggerType": "resultsCount",
"savedQueryId": "Goatherd_sample_dataset_last_hour",
"triggerComparator": ">=",
"triggerCount": 10,
"message": "Date: {{timestamp}}\n\nA notification was triggered for the scheduled search: {{searchId}},\nTenant ID: {{tenantId}}\nSearch ID: {{savedQueryId}}.\nNotification: {{notificationId}}"
},
"targetConfigs": [
{
"id": "slack_hourly_webhook",
"conf": {
"includeResults": true,
"attachmentType": "inline"
}
}
],
"metadata": [
{
"name": "team",
"value": "dataops"
},
{
"name": "'alert_type'",
"value": "results_10_plus"
}
],
"group": "default_search",
"id": "goatherd_results_burst"
}
],
"count": 1
}