Build a receiver

This page is how you stand up an HTTPS endpoint that Tallwatch can POST incident events to. After it is reachable, you add a webhook channel and click Send test. A receiver that does not verify the signature will accept forged POSTs from anyone who learns the URL. A receiver that takes longer than 10 seconds looks like a timeout, so Tallwatch retries. Get the endpoint, the secret, and the 2xx response in place before you route real incidents through it.

Expose an HTTPS POST endpoint

You need an HTTPS POST endpoint that verifies the signature and returns 2xx within 10 seconds.Private and metadata URLs are blocked. For local work, tunnel localhost (ngrok, cloudflared) so the URL Tallwatch calls is public HTTPS, not http://127.0.0.1.

Generate a shared secret

Generate a secret (openssl rand -base64 32), store it as TALLWATCH_WEBHOOK_SECRET, and paste the same value into the channel.

openssl rand -base64 32

Tallwatch uses this value to compute X-Tallwatch-Signature. Your process uses the same value to recompute it. If they differ, every delivery returns 401.

Scaffold the handler

The prompt below is a spec you paste into Cursor, Claude Code, or a similar coding agent. It tells the agent to read the raw body, verify HMAC-SHA256, handle the incident events, and return 2xx without pulling in a webhook framework. Replace <REPLACE> with your stack.Copy this prompt into Cursor, Claude Code, or similar:

Build a POST /webhooks/tallwatch receiver for Tallwatch.

Stack: <REPLACE>.

1. Read the RAW body before JSON parsing.
2. Header X-Tallwatch-Signature is t=<unix>,v1=<hex>.
   HMAC-SHA256(secret, "t=" + t + "." + rawBody), hex-encode, constant-time compare to v1.
   401 if mismatch or t is more than 300s off. Secret: TALLWATCH_WEBHOOK_SECRET.
3. Parse JSON. Handle incident.opened, incident.acknowledged, incident.resolved, test.
   Shape: { event, occurred_at, org, monitor, incident, check }.
4. Return 204 within 10s. Slow work: 202 then process async.
5. Idempotent on incident.id. Unit test: valid signature → 204, tampered → 401.
Use the standard library. No webhook framework.

Add the channel and send a test

Then add the channel in and click Send test.Send test POSTs to your URL with event set to test. Use it to confirm TLS, the signature, and a 2xx before a real outage fires the channel.

Status codes and retries

Return any 2xx. 204 is enough when you finished the work inline. Return 202 if you only accepted the body and will process it asynchronously; that still counts as success and must happen within 10 seconds. 5xx / 429 / timeout retry up to 3 times; 4xx does not. A 401 on a bad signature is the right call (Tallwatch should not retry a request you rejected as forged). A 400 because your parser threw on a valid body is not retried either, so treat parse failures as 5xx only if you want another attempt.

Webhook channels need Pro or Business. See for the channel fields.

See and .

Monitors

Alerts

Status pages

Developers

Status codes and retries

​Status codes and retries

Status codes and retries