Agent skill

Databricks Webhooks Skill

Receive and authenticate Databricks webhooks. Use when setting up a Databricks workspace notification destination of type Webhook, securing the endpoint with HTTP Basic auth (Databricks has no payload signature), or handling job events like jobs.on_start, jobs.on_success, jobs.on_failure, jobs.on_duration_warning_threshold_exceeded and SQL alert state changes.

Install this skill

npx skills add hookdeck/webhook-skills --skill databricks-webhooks

Databricks POSTs JSON to a workspace notification destination of type Webhook when a job or task run starts, succeeds, fails, or exceeds its duration threshold, and when a Databricks SQL alert changes state.

When to Use This Skill

How do I receive Databricks webhooks?
How do I verify Databricks webhooks? Is there a Databricks webhook signature?
How do I secure a Databricks webhook notification destination with Basic auth?
How do I handle jobs.on_success or jobs.on_failure events?
How do I handle Databricks SQL alert (alert_state_change) webhooks?
Why does my Databricks webhook endpoint return 401?

Verification (core)

Databricks does not sign webhook payloads. There is no signature header and no HMAC. When you create the Webhook destination you can set a username and password; Databricks then sends Authorization: Basic base64(username:password) on every request. Decode it and compare both values timing-safe:

const crypto = require('crypto');
const safeEqual = (a, b) => {
  const ab = Buffer.from(a), bb = Buffer.from(b);
  return ab.length === bb.length && crypto.timingSafeEqual(ab, bb);
};

function verifyDatabricksAuth(authHeader, username, password) {
  if (!authHeader || !username || !password || !authHeader.startsWith('Basic ')) return false;
  const decoded = Buffer.from(authHeader.slice(6), 'base64').toString('utf-8');
  const i = decoded.indexOf(':'); // passwords may contain ':'
  if (i === -1) return false;
  const userOk = safeEqual(decoded.slice(0, i), username);
  const passOk = safeEqual(decoded.slice(i + 1), password);
  return userOk && passOk;
}

The OAuth (Beta) option for webhook destinations uses client credentials and an access token; it is separate and not covered here. A destination can use Basic auth or OAuth, not both.

No body signature means the raw body isn't security-critical: normal JSON parsing is fine. Databricks requires an HTTPS endpoint with a certificate from a trusted CA, and publishes outbound IP ranges you can allowlist.

For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.

Common Event Types

Job and task payloads carry event_type:

`event_type`	Sent when
`jobs.on_start`	A run starts
`jobs.on_success`	A run stops and completed in a successful or succeeded-with-failures state
`jobs.on_failure`	A run stops in an unsuccessful state
`jobs.on_duration_warning_threshold_exceeded`	A run exceeds the configured duration threshold

Job payloads include workspace_id, run.run_id, job.job_id, job.name, and, for task-level notifications, task.task_key and run.parent_run_id.

SQL alerts send a different payload. It has no event_type; the field is event with the value alert_state_change, plus url_base and an alert object. See references/overview.md.

Environment Variables

DATABRICKS_WEBHOOK_USERNAME=your_destination_username
DATABRICKS_WEBHOOK_PASSWORD=your_destination_password

The examples fail closed (return 500) if either is missing.

Local Development

For local webhook testing, run the Hookdeck CLI via npx (no install required):

npx hookdeck-cli listen 3000 databricks --path /webhooks/databricks

No account required. The CLI provides a public URL that tunnels to your local server, plus a web UI for inspecting requests.

Reference Materials

references/overview.md - Webhook concepts, event types, payload fields
references/setup.md - Create a Webhook notification destination and attach it to jobs and alerts
references/verification.md - Basic auth details, gotchas, debugging
examples/ - Express, Next.js, and FastAPI handlers with tests