# Better Stack Webhooks

Better Stack's Uptime and incident management product can send an outgoing webhook to your URL
when an incident changes, a monitor changes or the on-call person changes. Webhooks are **not
signed**: there is no signing secret, HMAC or timestamp. A webhook can carry one of two static
credentials, and your endpoint authenticates the request by comparing it with the value you set:

1. **Basic auth** (`auth_username` and `auth_password`): `Authorization: Basic base64(username:password)`.
2. **A custom header** you add to the webhook's `headers_template`, for example
  `X-Better-Stack-Secret: <long random secret>`. The header name is yours to choose.

Hookdeck's Better Stack source offers both: **Basic auth** (the default) and **Custom header**
(an API key check on the header name you enter). Hookdeck's source checks the credential, so it must be on every request.

Better Stack's docs do **not** say whether Basic credentials are sent on the first request or only
after a `401 WWW-Authenticate` challenge. A receiver that never challenges only works if they are sent preemptively. The custom header avoids the question, so prefer
it; if Basic auth deliveries are rejected, switch to the custom header.

This skill covers the Uptime / incident management webhooks. Better Stack's Errors product has
separate outgoing webhooks with a different body and is out of scope.

## When to Use This Skill

* How do I receive Better Stack webhooks?
* How do I authenticate requests from a Better Stack outgoing webhook?
* Does Better Stack sign webhook payloads? (No: check Basic auth or a custom header)
* How do I handle incident, monitor and on-call change webhooks?
* How do I handle an incident `comment` webhook?
* Why does my Better Stack webhook endpoint return 401?

## Verification (core)

```javascript
const crypto = require('crypto');

// Hash both sides: equal-length digests, so timingSafeEqual never throws.
const safeEqual = (a, b) =>
  crypto.timingSafeEqual(
    crypto.createHash('sha256').update(a).digest(),
    crypto.createHash('sha256').update(b).digest()
  );

function verifyBetterStackRequest(headers, env = process.env) {
  // Custom header: the whole value, verbatim (nothing stripped or trimmed).
  const name = (env.BETTER_STACK_WEBHOOK_HEADER || 'X-Better-Stack-Secret').toLowerCase();
  const value = headers[name];
  const headerOk =
    Boolean(env.BETTER_STACK_WEBHOOK_SECRET) && typeof value === 'string' &&
    safeEqual(Buffer.from(value, 'latin1'), Buffer.from(env.BETTER_STACK_WEBHOOK_SECRET));

  // Basic auth: strict base64, split on the FIRST colon, evaluate both parts.
  let basicOk = false;
  const m = /^basic +([A-Za-z0-9+/]+={0,2})$/i.exec(headers['authorization'] || '');
  const user = env.BETTER_STACK_WEBHOOK_USERNAME, pass = env.BETTER_STACK_WEBHOOK_PASSWORD;
  if (m && user && pass && m[1].length % 4 === 0) {
    const buf = Buffer.from(m[1], 'base64');
    const decoded = buf.toString('utf8');
    const i = decoded.indexOf(':');
    if (buf.toString('base64') === m[1] && i !== -1) {
      const userOk = safeEqual(Buffer.from(decoded.slice(0, i)), Buffer.from(user));
      const passOk = safeEqual(Buffer.from(decoded.slice(i + 1)), Buffer.from(pass));
      basicOk = userOk && passOk;
    }
  }
  return headerOk || basicOk; // either configured method; with neither configured: false
}

```

* A request passes if **either configured** method matches. A method whose env vars are unset is
  never used, so with neither configured every request is rejected (fail closed).
* Missing header, wrong scheme, malformed value or mismatch: `401`. Check it before reading the
  body, for **every** HTTP method.
* Compare in constant time: Node `crypto.timingSafeEqual` on equal-length buffers (hash both
  sides); Python `hmac.compare_digest` on **bytes** (encode both sides; passing `str` raises
  `TypeError` on non-ASCII).
* Basic parsing: the `Basic` scheme matches in any case, base64 must be strict (Node's
  `Buffer.from(x, 'base64')` silently skips bad characters; Python needs
  `base64.b64decode(..., validate=True)`), and split on the first colon so a password may contain `:`.

**A static shared credential authenticates the sender, not the body, and gives no replay
protection** (there is no signature and no timestamp). Serve the endpoint over HTTPS, use a long
random value and rotate it if it leaks.

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/better-stack-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/better-stack-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/better-stack-webhooks/examples/fastapi/).

## Webhook Kinds and Events

Better Stack has three webhook kinds (`trigger_type`). The body is a user-editable template
(`body_template`), and no default `Content-Type` is documented, so read the raw body and parse
JSON only after the credential check.

| Kind | `trigger_type` | Fires when | Default body |
| --- | --- | --- | --- |
| Incident webhook | `incident_change` | An incident starts, is acknowledged, resolved, reopened or commented on | `data.type: "incident"`, `data.attributes` (`name`, `url`, `http_method`, `cause`, `started_at`, `acknowledged_at`, `resolved_at`, `response_content`, `response_url`, `screenshot_url`) |
| Monitor webhook | `monitor_change` | A monitor is created, updated, paused, unpaused or deleted | `data.type: "monitor"`, `data.attributes` (`url`, `pronounceable_name`, `monitor_type`, `check_frequency`, `paused_at`, `last_checked_at`, ...) |
| On-call change webhook | `on_call_change` | An on-call contact changes, or a holiday starts or ends during a shift | `data` with `message`, `emails`, `on_holiday_emails`, `change`, `calendar_id`, `calendar_name`, `primary_calendar` |

**Only `comment` is a documented wire value.** When an incident is commented on, the body has a
top-level `"event": "comment"` and a top-level `comment` object (`id`, `type: "incident_comment"`,
`attributes` with `content`, `created_at`, `updated_at`, `user_id`, `user_email`) next to `data`.
Better Stack does not document whether the other incident deliveries carry `event`, or its values,
and monitor webhooks document no `event` field, so don't invent names like `incident.started`.
On-call webhooks carry `data.change`: `holiday` when only a holiday started or ended, `on_call`
otherwise.

The examples therefore dispatch on the **shape** of the body: `data.type` `incident` (`comment`
when the top-level `event` is `comment`; otherwise `resolved_at` set means resolved,
`acknowledged_at` set means acknowledged, else started/open, which is an inference), `data.type`
`monitor` (`paused_at` set means paused), and `data.change` `on_call` / `holiday`. Anything else
is logged. A customised `body_template` may carry none of these fields.

After authenticating, treat every field as untrusted: check types before reading into the body.
A non-JSON body (a custom template) is acknowledged and logged, not a 500.

## HTTP Methods

`custom_webhook_template_attributes.http_method` is one of `get`, `post`, `put`, `patch`, `head`
or `options` (default `post`), so the examples accept all six on the webhook route. An
authenticated request with no body is acknowledged with `200`.

Hookdeck's Better Stack source accepts only the methods you allow ([custom methods](https://hookdeck.com/docs/sources#custom-methods)). If the webhook uses
another method, also allow it on the source. Hookdeck sources can allow `GET`, `HEAD`, `POST`,
`PUT` and `PATCH` but not `OPTIONS`, so don't use `options` for a webhook routed through Hookdeck.

## Environment Variables

```bash
# Custom header: added to the webhook's headers_template
BETTER_STACK_WEBHOOK_HEADER=X-Better-Stack-Secret   # your header name (this is the default)
BETTER_STACK_WEBHOOK_SECRET=your-long-random-secret # the header's exact value
# Basic auth: the webhook's auth_username and auth_password
BETTER_STACK_WEBHOOK_USERNAME=betterstack
BETTER_STACK_WEBHOOK_PASSWORD=your-password

```

## Delivery

The Uptime pages document no timeout, retry policy or source IP list. Answer quickly with a 2xx
and process asynchronously. No delivery ID is documented, so deduplicate on the incident or monitor
`data.id` plus the state if repeats matter.

## Local Development

Better Stack can't reach `localhost`. Tunnel with the Hookdeck CLI (no account required):

```bash
npx hookdeck-cli listen 3000 better-stack --path /webhooks/better-stack

```

Use the printed URL as the webhook's URL.

## Resources

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/better-stack-webhooks/references/overview.md) - Webhook kinds, payload shapes and states
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/better-stack-webhooks/references/setup.md) - Add a webhook, Basic auth vs custom header, Hookdeck source
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/better-stack-webhooks/references/verification.md) - Credential check details, gotchas, debugging 401s
* [examples/](https://github.com/hookdeck/webhook-skills/tree/main/skills/better-stack-webhooks/examples/) - Runnable Express, Next.js and FastAPI handlers with tests