Gareth Wilson Gareth Wilson

Guide to Better Stack Webhooks: Features and Best Practices

Published


Better Stack webhooks tell your systems when something changes in Better Stack's uptime monitoring and incident management. An incident starts, gets acknowledged or resolved, a monitor is paused, or the on-call contact changes, and Better Stack sends a request to your URL. Teams use them to sync incidents into ticketing tools, post status to internal dashboards, trigger runbooks, or keep a record of who was on call.

This guide covers the three webhook kinds, the request template that decides what each request contains, how to authenticate requests that Better Stack doesn't sign, and the practices that keep a receiver reliable.

What are Better Stack webhooks?

Better Stack calls them outgoing webhooks. Each one has a URL, a kind and a request template:

  • Incident webhook (incident_change): fires when an incident is created, acknowledged, resolved, reopened, or commented on.
  • Monitor webhook (monitor_change): fires when a monitor is created, updated, paused, unpaused, or deleted.
  • On-call change webhook (on_call_change): fires when the on-call contact changes, or when someone's holiday starts or ends during their shift.

The request template sets the HTTP method, the body, any headers, and optional HTTP Basic credentials. Requests are not signed, and nothing in them is computed from the body. If you add neither credentials nor a secret header, a request carries nothing that proves it came from Better Stack.

Better Stack's Errors product has its own outgoing webhooks with a different body. This guide covers the Uptime and incident management webhooks.

Better Stack webhook features

FeatureDetails
ConfigurationIncidents > Integrations > Exporting data > Outgoing webhooks, or POST /api/v2/outgoing-webhooks
Kindsincident_change, monitor_change, on_call_change
Incident triggersStarted, acknowledged, resolved, reopened, comment. Each can be turned off, and all default to on
Methodpost (default), get, put, patch, head or options
BodyA template with $VARIABLES. Each kind has a default JSON template
Metadata$METADATA variables render the incident's or monitor's metadata
AuthenticationHTTP Basic (auth_username and auth_password), or custom headers
Signature and timestampNone
Timeout, retries, source IPsNot documented for these webhooks

What a request contains

Each kind has a default body template. The incident template is:

{
  "data": {
    "id": "$INCIDENT_ID",
    "type": "incident",
    "attributes": {
      "name": "$NAME",
      "url": "$URL",
      "http_method": "$HTTP_METHOD",
      "cause": "$CAUSE",
      "started_at": "$STARTED_AT",
      "acknowledged_at": "$ACKNOWLEDGED_AT",
      "resolved_at": "$RESOLVED_AT",
      "response_content": "$RESPONSE_CONTENT",
      "response_url": "$RESPONSE_URL",
      "screenshot_url": "$SCREENSHOT_URL"
    }
  }
}

The monitor template has data.type monitor and the monitor's settings under data.attributes, such as url, pronounceable_name, monitor_type, check_frequency and paused_at. The on-call template puts message, emails, on_holiday_emails, change, calendar_id, calendar_name and primary_calendar under data. change is holiday when only a holiday started or ended, and on_call otherwise.

When an incident gets a comment, the body also has a top-level event and a comment object. Better Stack's example, shortened:

{
  "event": "comment",
  "data": {
    "id": "1",
    "type": "incident",
    "attributes": {
      "name": "Tesla.com homepage",
      "cause": "Error 500",
      "started_at": "2020-10-21T10:51:28.151Z",
      "acknowledged_at": "2020-02-25T17:38:45.768Z",
      "resolved_at": null
    },
    "relationships": {
      "monitor": {
        "data": { "id": "4", "type": "monitor" }
      }
    }
  },
  "comment": {
    "id": "42",
    "type": "incident_comment",
    "attributes": {
      "content": "Investigating — the database has been failing over.",
      "created_at": "2020-10-21T10:55:12.812Z",
      "user_id": 7,
      "user_email": "jane@example.com"
    }
  }
}

comment is the only event value the docs show. Whether started, acknowledged, resolved and reopened requests carry event, and with which values, isn't documented, so don't route on it alone. data.type tells incident and monitor requests apart, and the incident timestamps show how far an incident has got.

You can replace any template. Metadata variables such as $METADATA.Severity render as text, while $METADATA.Owner.values and $METADATA_ARRAY render whole JSON values and go in the template without quotes. New webhooks render these with metadata_api_version v3. Webhooks that used metadata variables before v3 existed stay on v2 until you change it through the API.

Inspect Better Stack webhooks as they arrive. Better Stack's docs suggest Hookdeck for testing webhooks. Point a webhook at a Hookdeck Inspect URL and trigger an incident to see exactly what your template sends, with no account or setup required.

Setting up Better Stack webhooks

Pick a header name and a long random value first, for example X-Better-Stack-Secret with the output of openssl rand -hex 32.

  1. In Better Stack, go to Incidents > Integrations > Exporting data and find Outgoing webhooks.
  2. Click Configure, then Add on the Incident webhook, Monitor webhook or On-call change webhook card.
  3. Enter your HTTPS Webhook URL.
  4. Pick which events trigger the webhook, and customise the request template.
  5. Save, then trigger a test incident or pause a test monitor.

The API calls the template's settings custom_webhook_template_attributes. This request creates an incident webhook that sends the secret header:

curl -X POST "https://incidents.betterstack.com/api/v2/outgoing-webhooks" \
  -H "Authorization: Bearer $BETTER_STACK_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Incidents to my service",
    "url": "https://example.com/webhooks/better-stack",
    "trigger_type": "incident_change",
    "custom_webhook_template_attributes": {
      "http_method": "post",
      "headers_template": [
        { "name": "Content-Type", "value": "application/json" },
        { "name": "X-Better-Stack-Secret", "value": "your-long-random-value" }
      ]
    }
  }'

To change an existing webhook, send the same attributes with PATCH /api/v2/outgoing-webhooks/{outgoing_webhook_id}.

With Hookdeck. Create a Hookdeck source with the Better Stack type and use its URL as the webhook URL. Verification is optional on this source and starts on Basic Auth. Switch it to Custom header, then enter the header name as Header and the secret as Header Value. Hookdeck compares the value exactly as you enter it.

Basic Auth also works if Better Stack sends the Authorization header with each request, but its docs don't say whether it does that or waits for a 401 challenge first. Hookdeck never sends a challenge, so the custom header is the safer choice.

The source pre-selects POST without managing the method. If your template uses another method, allow it on the source too. Requests that fail verification still get a 200 from Hookdeck, but they're recorded as failed and never reach your service.

Securing Better Stack webhooks

Compare the secret header with your stored value in constant time. Look the header up case-insensitively, compare the whole value, and check lengths before calling crypto.timingSafeEqual.

const crypto = require('crypto');
const express = require('express');

const HEADER = (process.env.BETTER_STACK_WEBHOOK_HEADER || 'X-Better-Stack-Secret').toLowerCase();
const SECRET = process.env.BETTER_STACK_WEBHOOK_SECRET;

function safeEqual(a, b) {
  const x = Buffer.from(a, 'utf8');
  const y = Buffer.from(b, 'utf8');
  return x.length === y.length && crypto.timingSafeEqual(x, y);
}

function verifyBetterStackRequest(headers) {
  if (!SECRET) return false; // fail closed when unconfigured
  const received = headers[HEADER]; // Node lower-cases incoming header names
  return typeof received === 'string' && safeEqual(received, SECRET);
}

const app = express();

// Use app.put or app.patch instead if your template sends another method.
app.post('/webhooks/better-stack', express.raw({ type: '*/*' }), async (req, res) => {
  if (!verifyBetterStackRequest(req.headers)) {
    return res.sendStatus(401);
  }

  let body;
  try {
    body = JSON.parse(req.body.toString('utf8'));
  } catch {
    return res.sendStatus(400);
  }
  const data = body && typeof body === 'object' ? body.data : null;
  if (!data || typeof data !== 'object') return res.sendStatus(400);

  try {
    if (data.type === 'incident') {
      await queue.add('better-stack-incident', { incidentId: data.id, event: body.event, data, comment: body.comment });
    } else if (data.type === 'monitor') {
      await queue.add('better-stack-monitor', { monitorId: data.id, data });
    } else if (typeof data.change === 'string') {
      await queue.add('better-stack-on-call', data);
    }
  } catch {
    return res.sendStatus(503);
  }
  res.sendStatus(200);
});

queue is a placeholder for your job queue. The branches match the default templates, so change them if you replace the body.

The same check in Python:

import hmac
import os


def verify_better_stack_request(headers) -> bool:
    secret = os.environ.get("BETTER_STACK_WEBHOOK_SECRET")
    if not secret:
        return False
    name = os.environ.get("BETTER_STACK_WEBHOOK_HEADER", "X-Better-Stack-Secret")
    received = headers.get(name)  # case-insensitive in Starlette and Flask
    if not received:
        return False
    return hmac.compare_digest(received.encode("utf-8"), secret.encode("utf-8"))

A static header proves the sender knows the value. It doesn't prove the body is unchanged, and with no timestamp a captured request can be replayed. Serve the endpoint over HTTPS only, keep the value long and random, and change it on the webhook and in your environment together if it might have leaked.

Make Better Stack webhooks production-ready. Hookdeck Event Gateway checks your header on every Better Stack request, queues each incident and monitor change durably, and retries delivery to your service on a schedule you control.

Better Stack webhook limitations and pain points

No signature

The Problem: Anyone who learns your webhook URL can send requests that look like incidents.

Why It Happens: Better Stack doesn't sign outgoing webhooks. Its template offers Basic credentials and custom headers, both static.

Workarounds:

  • Add a secret header or Basic credentials to every webhook, and reject requests without them.
  • Re-read important state, such as whether an incident is still open, from Better Stack's API before acting on it.

How Hookdeck Can Help: Hookdeck's Better Stack source compares the header or credentials you enter on every request, and records requests that don't match as failed verification instead of delivering them.

Basic credentials and challenges

The Problem: A webhook set up with Basic authentication fails verification even though the username and password are right.

Why It Happens: Better Stack's docs give fields for the username and password but don't say whether they're sent with the first request or only after a 401 challenge. A receiver that never challenges, like Hookdeck, only sees credentials sent up front.

Workarounds:

  • Use a custom header, which Better Stack sends as part of the template.
  • If you prefer Basic, send a test request to Hookdeck Inspect and check that it has an Authorization header.

How Hookdeck Can Help: Hookdeck keeps every request with its headers, so you can see whether credentials arrived before you rely on them.

Event names are thin

The Problem: Your receiver can't tell an acknowledgement from a resolution, or ignores monitor changes it should handle.

Why It Happens: The default templates carry no event name. Only incident comments are documented with a top-level event, and monitor webhooks don't say which change happened.

Workarounds:

  • Use one webhook per kind, so the URL or data.type tells you the kind.
  • Read the incident's acknowledged_at and resolved_at to work out its state.
  • Turn off incident triggers you don't need with the on_incident_* settings.

How Hookdeck Can Help: Hookdeck filters can route on any body field, such as data.type or event, so each kind reaches the right handler.

No documented delivery behaviour

The Problem: You can't tell from the docs how long Better Stack waits for your endpoint, whether it retries, or what happens when your service is down.

Why It Happens: The outgoing webhooks pages cover configuration and templates, not timeouts or retries.

Workarounds:

  • Respond quickly and process afterwards, so a slow handler doesn't become a lost incident update.
  • Reconcile open incidents with Better Stack's API on a schedule.

How Hookdeck Can Help: Hookdeck accepts each request as soon as it arrives and stores it, then delivers to your service with retries you configure. You can replay any request after a fix, and issues alert you when deliveries to your service fail.

Best practices

Keep a template contract

Treat each webhook's template as an API. Include the kind, the incident or monitor ID, and the timestamps you need, and change it only when your receiver is ready.

Make handlers idempotent

A repeated request shouldn't open a second ticket. Key on the incident ID plus its state, or on the comment ID for comments, and store the key before acting. See our guide to webhook idempotency.

Move metadata to v3 deliberately

If an older webhook uses metadata variables, it may still render the legacy v2 shapes. Update your receiver for v3 first, then switch metadata_api_version through the API.

Acknowledge fast and process asynchronously

Check the header, store the request, return 200, and do the work afterwards. See why to process webhooks asynchronously.

Conclusion

Better Stack's outgoing webhooks report incident, monitor and on-call changes with a body you shape through a template, and they aren't signed. Add a secret header, compare it in constant time over HTTPS, put the IDs and timestamps you need in the template, allow every method you configure, and build the handler to cope with repeats and undocumented delivery behaviour.

Hookdeck Event Gateway checks the header, keeps every request, and retries and replays delivery to your service, so an outage on your side doesn't mean a missed incident.

Get started with Hookdeck for free and handle Better Stack webhooks reliably in minutes.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.