SQL alert webhook payload

When a Databricks SQL alert changes state, a webhook notification destination receives a JSON payload that describes the alert and its evaluation. This payload format applies to the latest version of Databricks SQL alerts. Legacy alerts use a different payload.

Important

Alert configurations determine which additional fields the payload includes. Fields without values are omitted. Configure your webhook receiver to ignore unknown fields and handle missing optional fields.

Payload example

The following example shows the payload for an alert that changed to the TRIGGERED state. Identifiers, names, and timestamps are fictional examples.

{
  "event": "alert_state_change",
  "url_base": "https://<workspace-url>/sql?o=1234567890123456",
  "alert": {
    "title": "Alert \"Daily revenue\" changed status to TRIGGERED",
    "description": "Daily revenue exceeded the configured threshold.",
    "alert": {
      "id": "9876543210987654",
      "name": "Daily revenue",
      "owner": {
        "id": 2468013579246801,
        "name": "Alex Smith",
        "email": "alex.smith@example.com"
      },
      "created_at": 1767225600000,
      "parent": "folders/1357924680135792",
      "query_text": "SELECT SUM(revenue) AS total_revenue FROM main.sales.daily",
      "warehouse_id": "4b9b953939869799",
      "custom_summary": "Alert \"{{ALERT_NAME}}\" changed status to {{ALERT_STATUS}}",
      "custom_description": "Daily revenue exceeded the configured threshold.",
      "evaluations": [
        {
          "id": "9a1f0fc0-7d18-4f42-8ec0-9c1f8e72d3a4",
          "source": {
            "name": "total_revenue",
            "display": "total_revenue",
            "aggregation": "AGGREGATION_UNSPECIFIED"
          },
          "comparison_operator": "GREATER_THAN",
          "threshold": {
            "value": {
              "double_value": 100000.0
            }
          },
          "empty_result_state": "OK",
          "notification": {
            "seconds_to_retrigger": 3600,
            "notify_on_ok": true,
            "subscriptions": [
              {
                "destination_id": "6d1f7e62-a9d4-4b32-b79d-2b1f9f5a6c80"
              }
            ]
          },
          "state": "TRIGGERED",
          "last_evaluated_at": 1767229200000,
          "last_triggered_at": 1767229200000
        }
      ],
      "schedule": {
        "quartz_cron_schedule": "0 0 * * * ?",
        "timezone_id": "UTC",
        "paused": false
      },
      "custom_template_format": "HTML"
    }
  }
}

Payload fields

The payload contains the following envelope fields:

Field Type Description
event String The event type. For alert state changes, the value is alert_state_change.
url_base String The base URL for Databricks SQL in the workspace.
alert Object The notification and alert details.
alert.title String The rendered custom notification subject. This field is omitted when the alert doesn't define a custom subject.
alert.description String The rendered custom notification body. This field is omitted when the alert doesn't define a custom body.
alert.alert Object A snapshot of the alert when the notification was sent.

The nested alert.alert object can contain the following fields:

Field Type Description
id String The alert resource ID.
name String The alert name.
owner Object The alert owner's ID, name, and email address. This field is omitted when owner details aren't available.
created_at Integer The alert creation time, in milliseconds since the Unix epoch.
parent String The resource name of the folder that contains the alert.
query_text String The SQL query that the alert evaluates.
warehouse_id String The ID of the SQL warehouse that runs the query.
custom_summary String The custom notification subject template. This field is omitted when a custom subject isn't configured.
custom_description String The custom notification body template. This field is omitted when a custom body isn't configured.
custom_template_format String The format of the custom templates, such as HTML or MARKDOWN.
evaluations Array The configured evaluation conditions and their state. The state value reflects the state change that caused the notification.
schedule Object The Quartz cron schedule, time zone, and paused state. This field is omitted when the alert doesn't have a schedule.

Depending on the alert configuration, the nested object can also include parameters, genie_analysis_enabled, genie_analysis_custom_prompt, and genie_analysis_references.

Each object in the evaluations array can contain the following fields:

Field Type Description
id String The evaluation condition ID.
source Object The query result column and aggregation that the condition evaluates.
comparison_operator String The comparison operator, such as GREATER_THAN, EQUAL, or IS_NULL.
threshold Object The value or query result column that the source is compared against.
empty_result_state String The state to use when the query returns no rows. This field is omitted when the alert doesn't define an empty result state.
notification Object The retrigger interval, notify-on-OK setting, and notification destination IDs.
state String The evaluation state that caused the notification: TRIGGERED, OK, or ERROR.
last_evaluated_at Integer The evaluation time, in milliseconds since the Unix epoch.
last_triggered_at Integer The last triggered time, in milliseconds since the Unix epoch. This field is omitted when the alert hasn't triggered.

Secure the webhook payload

The payload can contain sensitive workspace metadata, including the SQL query, the alert owner's identity, and custom notification content. Protect the receiving endpoint and limit access to stored payloads. For webhook networking and authentication options, see Manage notification destinations.

  • Last updated on