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.

JSON

{
  "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.

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.

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.

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.