better-stack-webhooks

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, compared against the whole value). Hookdeck's source checks the credential; it never answers with a 401 challenge.

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 (including Hookdeck's source) 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
}