> ## Documentation Index
> Fetch the complete documentation index at: https://docs.manalens.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Alert webhooks

> Payload, headers and signature verification for alert webhooks.

When an [alert](https://docs.manalens.dev/features/alerts.md) with a webhook destination fires, ManaLens sends a signed `POST` request with a JSON body to your HTTPS URL.

## Payload

```json theme={null}
{
  "id": "evt_6c1f0e2a-3b7d-4c55-9a0e-1f2d3c4b5a69",
  "type": "alert.threshold_reached",
  "created": 1762603200,
  "data": [
    {
      "alert_id": "a3b1c2d4-...",
      "alert_name": "Signups spiking",
      "event_name": "signup_completed",
      "condition": "above",
      "threshold": 10,
      "trigger_filters": [
        { "field": "country", "op": "in", "value": ["US", "SG"] }
      ],
      "observed_count": 14,
      "window_start": "2026-11-08T12:00:00.000Z",
      "window_end": "2026-11-08T12:05:00.000Z"
    }
  ]
}
```

| Field | Description |
| - | - |
| `id` | The delivery ID. It stays the same on each retry of one delivery, so you can drop duplicates by `id`. |
| `type` | `alert.threshold_reached`, or `alert.test` for a test send |
| `created` | Unix time in seconds |
| `data[].condition` | `above` (at least `threshold` events) or `below` (fewer than `threshold` events) |
| `data[].threshold` | The count in the condition |
| `data[].trigger_filters` | The alert's filters, ANDed: `{field, op, value}` the same fields and operators as the report filter menu. A list operator (`in`, `nin`) has an array value. An existence operator (`notEmpty`, `isEmpty`) has no value. Empty when the alert has no filters. |
| `data[].observed_count` | The event count in the five-minute window. It can be `0` for a `below` alert. |
| `data[].window_start`, `window_end` | The UTC window |

Both conditions use the type `alert.threshold_reached`. Read `data[].condition` to tell them apart.

The condition, threshold and filters in a delivery are the ones the window fired under. If someone edits the alert after that, a retry of the same delivery still sends the old values.

A test send has `"type": "alert.test"`, a new `id`, `data[0].test = true`, and the alert's current `condition`, `threshold` and `trigger_filters`. It has no count or window.

## Headers

| Header | Value |
| - | - |
| `X-Webhook-Signature` | Hex HMAC-SHA256 of `{timestamp}.{raw body}`, keyed with the alert's signing secret |
| `X-Webhook-Timestamp` | Unix time in seconds when the request was signed |
| `X-Webhook-Event` | The payload `type` |

## Verify the signature

The signing secret (`whsec_...`) is shown once, when you create the alert or when you change the alert to a new webhook URL. A new URL always gets a new secret. To verify a request:

1. Read the **raw** request body. Do not parse and re-serialize it first.
2. Refuse a timestamp more than five minutes from your clock.
3. Compute the HMAC-SHA256 of `{timestamp}.{raw body}` with the secret.
4. Compare it with `X-Webhook-Signature` in constant time.

The timestamp is inside the signed string, so an attacker cannot replay an old body with a new timestamp.

```js Node.js theme={null}
import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(rawBody, headers, secret) {
  const timestamp = headers['x-webhook-timestamp'];
  if (!/^\d+$/.test(timestamp) || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest();
  const given = Buffer.from(headers['x-webhook-signature'] || '', 'hex');
  return given.length === expected.length && timingSafeEqual(given, expected);
}
```

## Delivery rules

* Respond with a `2xx` status. Any other result, including a `3xx` redirect, is a failed delivery.
* A request times out after 5 seconds. The response body is ignored.
* Failed deliveries retry with backoff, up to five attempts. Delivery is at least once.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.