# 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:

```javascript
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/](https://github.com/hookdeck/webhook-skills/tree/main/skills/databricks-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/databricks-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/databricks-webhooks/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](https://github.com/hookdeck/webhook-skills/blob/main/skills/databricks-webhooks/references/overview.md).

## Environment Variables

```bash
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):

```bash
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](https://github.com/hookdeck/webhook-skills/blob/main/skills/databricks-webhooks/references/overview.md) - Webhook concepts, event types, payload fields
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/databricks-webhooks/references/setup.md) - Create a Webhook notification destination and attach it to jobs and alerts
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/databricks-webhooks/references/verification.md) - Basic auth details, gotchas, debugging
* [examples/](https://github.com/hookdeck/webhook-skills/tree/main/skills/databricks-webhooks/examples/) - Express, Next.js, and FastAPI handlers with tests