# Guide to Better Stack Webhooks: Features and Best Practices

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

| Feature | Details |
| --- | --- |
| Configuration | **Incidents > Integrations > Exporting data > Outgoing webhooks**, or `POST /api/v2/outgoing-webhooks` |
| Kinds | `incident_change`, `monitor_change`, `on_call_change` |
| Incident triggers | Started, acknowledged, resolved, reopened, comment. Each can be turned off, and all default to on |
| Method | `post` (default), `get`, `put`, `patch`, `head` or `options` |
| Body | A template with `$VARIABLES`. Each kind has a default JSON template |
| Metadata | `$METADATA` variables render the incident's or monitor's metadata |
| Authentication | HTTP Basic (`auth_username` and `auth_password`), or custom headers |
| Signature and timestamp | None |
| Timeout, retries, source IPs | Not documented for these webhooks |

## What a request contains

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

```json
{
  "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:

```json
{
  "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](https://inspect.hookdeck.com) 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:

```bash
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`.

```javascript
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:

```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](/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](https://inspect.hookdeck.com) 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](/docs/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](/docs/retries) you configure. You can replay any request after a fix, and [issues](/docs/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](/webhooks/guides/implement-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](/webhooks/guides/why-implement-asynchronous-processing-webhooks).

## 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](https://hookdeck.com) 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](https://dashboard.hookdeck.com/signup) for free and handle Better Stack webhooks reliably in minutes.