How to set up and verify webhook alerts

A webhook channel POSTs JSON to a URL you choose when a monitor goes down or recovers, and for other alerts such as slow responses, expiring certificates and changed DNS records. Each request is signed, so your endpoint can check that it really came from Uptimecheck.

Add the webhook

1. Open Alert channels in the sidebar and choose Add channel.
2. Pick Webhook and enter the Endpoint URL.
3. Choose Add channel and copy the signing secret that appears. It is shown only once.
4. Choose Send test to send a test call.

Verify the signature

Every request carries two headers:

• x-uptimecheck-timestamp: Unix time in seconds when the request was signed.
• x-uptimecheck-signature: sha256= followed by the hex HMAC-SHA256 of the timestamp, a dot and the raw body, keyed with the channel’s signing secret.

Compute the same value from the raw body before you parse it, compare in constant time, and reject old timestamps. In Node.js:

import { createHmac, timingSafeEqual } from "node:crypto";

export function isFromUptimecheck(rawBody, headers, secret) {
  const timestamp = headers["x-uptimecheck-timestamp"] ?? "";
  const signature = headers["x-uptimecheck-signature"] ?? "";
  const expected = "sha256=" + createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300;
  return fresh && signature.length === expected.length && timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

A Python version and every field of the payload are in the API documentation.

Good to know

• Answer with any 2xx status within 10 seconds. Anything else is retried four more times, after 30 s, 2 min, 10 min and 30 min.
• The event field says what happened, such as monitor.down, monitor.up, monitor.slow, certificate.expiring or dns.changed. The API reference lists every event and shows how to verify the signature.
• Use HTTPS, and do slow work after you have answered.

See all alert channels, or automate setup with the REST API.