Get Alerts for Search Results
Use the Cribl API to configure a Notification target and Notification so that you can receive alerts based on the results of a scheduled search.
About Code Examples
Code examples use Bearer token authentication. Read the API authentication documentation to learn how to configure authentication. The API Credential that you use to obtain the Bearer token must have the necessary Permissions for the operations in code examples.
Replace the variables in code examples with the corresponding information for your Cribl deployment.
Cribl Search is available only on Cribl.Cloud, so these code examples do not include on-prem deployments.
Code examples do not include all available body parameters. For a complete list of body parameters for specific endpoints, refer to the documentation in the API Reference.
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
You can 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
}