# Lampwick alerts as signed webhooks

> Lampwick POSTs alerts and new or reopened issues as signed JSON to your own HTTPS endpoint, with an HMAC-SHA256 signature you check with the channel's secret.

A webhook channel sends a team's alerts, and its new and reopened issues, to your own `https://` endpoint as a `POST` with a JSON body. Use it to open a ticket, page someone or start a script.

## What you get

- One request per alert or issue, with `event` (such as `monitor_down`, `new_issue`, `regression` or `test`), `title`, `body`, a dashboard `url`, and the project and team.
- `X-Lampwick-Signature`: `v1=` and the hex HMAC-SHA256 of `TIMESTAMP.BODY`, keyed with the channel's signing secret (`whsec_…`).
- `X-Lampwick-Delivery`, the same on retries, so you can drop duplicates.
- Retries on a network error, timeout, `408`, `429` or `5xx`: 4 times, over about 8 minutes.

## Set it up

1. Click **Alert channels** in the sidebar.
2. Under **Add a channel**, pick **Webhook** as the **Kind**, give it a **Name** and paste your endpoint's `https://` URL (port 443 or 8443).
3. Under **Alerts of**, pick **All projects** of a team or one project, and click **Add channel**.
4. Copy the signing secret from the channel's page, then click **Send test message**.

Check the signature before you trust a request. In Python:

```python
import hashlib
import hmac
import time

def verify(secret: str, timestamp: str, body: bytes, signature: str) -> bool:
    if abs(time.time() - int(timestamp)) > 300:
        return False
    expected = "v1=" + hmac.new(secret.encode(), timestamp.encode() + b"." + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)
```

Pass the raw request body, and the `X-Lampwick-Timestamp` and `X-Lampwick-Signature` headers. It refuses requests older than 5 minutes and compares in constant time.

## Let your agent do it

```text
Add an endpoint to this app that receives Lampwick alert webhooks. Read the "Webhook requests" section of https://lampwick.dev/docs/alerts.md. Verify X-Lampwick-Signature (v1= hex HMAC-SHA256 of "TIMESTAMP.BODY" with the secret from the LAMPWICK_WEBHOOK_SECRET environment variable) over the raw body in constant time, refuse timestamps older than 5 minutes, drop repeated X-Lampwick-Delivery ids, and answer 2xx quickly.
```

## Next step

The [webhook requests docs](/docs/alerts/#webhook-requests) show every header and a full example body.