Agent skill

Better Stack Webhooks Skill

Receive and authenticate Better Stack (Uptime / incident management) outgoing webhooks. Use when setting up an incident, monitor or on-call change webhook, checking the Basic auth or custom header credential, debugging 401s, or handling incident comment, resolved and on-call change notifications. Better Stack does not sign webhooks.

Install this skill

npx skills add hookdeck/webhook-skills --skill 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)

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/, examples/nextjs/, 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.

Kindtrigger_typeFires whenDefault body
Incident webhookincident_changeAn incident starts, is acknowledged, resolved, reopened or commented ondata.type: "incident", data.attributes (name, url, http_method, cause, started_at, acknowledged_at, resolved_at, response_content, response_url, screenshot_url)
Monitor webhookmonitor_changeA monitor is created, updated, paused, unpaused or deleteddata.type: "monitor", data.attributes (url, pronounceable_name, monitor_type, check_frequency, paused_at, last_checked_at, ...)
On-call change webhookon_call_changeAn on-call contact changes, or a holiday starts or ends during a shiftdata 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). 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

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

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

Use the printed URL as the webhook's URL.

Resources


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 17, 2026

View on GitHub →