- Prepare an HTTPS endpointCreate a publicly reachable HTTPS URL that accepts POST requests with a JSON body.
- Add a Generic webhook destinationIn Integrations → Add destination, choose "Set up Generic webhook" and enter a Name and the Webhook URL.
- Create the signing secretChoose "Generate a signing secret" or paste your own, and copy it into your receiver before saving.
- SaveChoose "Add destination". The secret is stored encrypted and never shown again.
- Verify every requestRecompute the HMAC-SHA256 of "<t>.<raw body>" and compare it with v1 in the X-Monitoring-Signature header, then check the timestamp.
- Send a testChoose "Send test" and confirm your endpoint accepts it with a 2xx response.
A generic webhook sends each alert as a signed JSON POST to your HTTPS endpoint. Webhooks are available on every plan, including Free, and are the easiest way to connect Uptime Tracker to your own tools.
Before you start
Any plan works. You need a publicly reachable HTTPS endpoint that accepts POST requests; private and internal addresses, plain HTTP and redirects are refused.
Add the destination
- Go to Integrations → Add destination, find Generic webhook and choose Set up Generic webhook.
- Enter a Name and the Webhook URL.
- Choose Generate a signing secret, or paste your own into Signing secret. Copy it into your receiver now: it is stored encrypted and cannot be shown again.
- Choose Add destination, then Send test. The destination is active immediately.
Request format
Each request has Content-Type: application/json and these headers:
X-Monitoring-Signature:t=<unix seconds>,v1=<hex HMAC-SHA256>X-Monitoring-Event-ID: the event id, for de-duplicationX-Monitoring-Schema: the envelope version, currently1
The body is an event envelope:
{
"id": "6f0c…",
"type": "monitor.down",
"occurred_at": "2026-10-05T09:14:03Z",
"data": {
"incident_id": "…",
"monitor_id": "…",
"monitor_name": "Checkout API",
"monitor_kind": "http",
"target": "api.example.com",
"category": "availability",
"opened_at": "2026-10-05T09:13:31Z",
"resolved_at": null,
"failure_reason": "HTTP 503 Service Unavailable"
}
}
Event types you can receive:
monitor.downandmonitor.recovered: a confirmed outage and its recovery.incident.reminder: a repeat reminder from a routing rule (data.remindercounts them).incident.escalation: an escalation policy step (data.step,data.on_call).incident.acknowledged: someone acknowledged the incident (data.actor).slo.budget_low,slo.budget_exhaustedandslo.fast_burn: SLO error-budget alerts (Team), with fields such asdata.slo_name,data.monitor_name,data.error_budget_remaining_percent,data.burn_rate_1h,data.burn_rate_6hand, forslo.budget_low,data.threshold_percent(50 or 25).destination.test: sent by Send test.integration.failed: another destination was disabled (data.reason).
The failure reason
data.failure_reason says why the check failed when the incident opened, in the same words as the Reason: line of chat and email alerts, for example HTTP 503 Service Unavailable, Timed out after 10s, TLS: certificate expired or not yet valid, Connection failed: connection refused, Keyword not found (HTTP 200), DNS: no such host or, for heartbeats, No heartbeat received within …. It is included on monitor.down, monitor.recovered, incident.reminder, incident.escalation and incident.acknowledged events. It is a short, human-readable string of at most 160 bytes, never a response body, header or URL, and it is null when the reason is unknown, so treat it as optional and do not parse it.
Other fields that do not apply to an event are left out, and new types may be added, so ignore types and fields you do not handle.
How the signature works
The signature is the hex HMAC-SHA256, keyed with your signing secret, of the timestamp, a dot, and the exact raw request body: <t>.<body>. Verify it against the raw bytes before parsing JSON, compare in constant time, and reject timestamps outside your replay window (5 minutes is a sensible default).
Node.js (Express)
const crypto = require('crypto');
const express = require('express');
const app = express();
const SECRET = process.env.UPTIME_WEBHOOK_SECRET;
const TOLERANCE_SECONDS = 300;
app.post('/hooks/uptime', express.raw({ type: 'application/json' }), (req, res) => {
const parts = {};
for (const piece of (req.get('X-Monitoring-Signature') || '').split(',')) {
const i = piece.indexOf('=');
if (i > 0) parts[piece.slice(0, i).trim()] = piece.slice(i + 1).trim();
}
const t = Number(parts.t);
if (!parts.v1 || !Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > TOLERANCE_SECONDS) {
return res.status(400).send('invalid signature');
}
const expected = crypto.createHmac('sha256', SECRET)
.update(parts.t + '.')
.update(req.body) // raw Buffer
.digest('hex');
const a = Buffer.from(expected, 'utf8');
const b = Buffer.from(parts.v1, 'utf8');
if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
return res.status(400).send('invalid signature');
}
const event = JSON.parse(req.body.toString('utf8'));
// Use event.id to ignore duplicates, then handle event.type.
res.sendStatus(204);
});
app.listen(3000);
Python (Flask)
import hashlib, hmac, json, os, time
from flask import Flask, abort, request
app = Flask(__name__)
SECRET = os.environ["UPTIME_WEBHOOK_SECRET"].encode()
TOLERANCE_SECONDS = 300
@app.post("/hooks/uptime")
def uptime_hook():
header = request.headers.get("X-Monitoring-Signature", "")
parts = dict(p.strip().split("=", 1) for p in header.split(",") if "=" in p)
try:
t = int(parts["t"])
signature = parts["v1"]
except (KeyError, ValueError):
abort(400)
if abs(time.time() - t) > TOLERANCE_SECONDS:
abort(400)
body = request.get_data() # raw bytes, before any JSON parsing
expected = hmac.new(SECRET, parts["t"].encode() + b"." + body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, signature):
abort(400)
event = json.loads(body)
# Use event["id"] to ignore duplicates, then handle event["type"].
return "", 204
Delivery and retries
Respond with any 2xx status within 15 seconds. Redirects are not followed. Failed deliveries are retried with backoff (about 5 seconds, 30 seconds, 2 minutes, 10 minutes and 30 minutes), and a Retry-After header is honored. Because a retry can repeat an event you already processed, de-duplicate by event id. After the last retry the delivery is marked failed. HTTP 401, 403, 404 and 410 are treated as permanent: the destination is disabled at once with the reason, and the workspace is told through its other destinations. Fix your endpoint, then choose Re-enable on the destination, or move it to a new URL with Edit connection. Integrations → Deliveries shows every attempt with its HTTP status.
Change the URL or rotate the signing secret
Choose Edit connection on the destination. Enter a new Webhook URL, a new Signing secret, or both (empty fields keep their current value), and choose Save connection. The URL is checked like a new one. Update your receiver before saving a new secret, because every request after the save is signed with it; to rotate without dropping events, have your receiver accept both the old and the new secret for a few minutes. The previous secret stays under Stored secrets on Integrations → Destinations until you delete it. Saving also re-enables a destination that was disabled after delivery failures.
Troubleshooting
- "Destination must be a publicly routable HTTPS endpoint": the URL uses HTTP, or its host resolves to a private or internal address.
- Signatures never match: verify against the raw request bytes, not re-serialized JSON, and make sure your framework does not decode or reformat the body first. The signed string is the
tvalue, a dot, then the body. - Timestamps rejected: check your server clock; a 5-minute tolerance is usually enough.
- "A name is required; webhooks need a signing secret": generate or paste a signing secret before saving.
failure_reasonis null: the reason was not known when the incident opened, for example for incidents opened before reasons were recorded. Handle it as optional.
Frequently asked questions
Which header carries the webhook signature?
X-Monitoring-Signature, formatted as t=
Can I see the signing secret again?
No. It is stored encrypted and never shown again. Copy it into your receiver before saving. To rotate it, enter a new secret with Edit connection on the destination.
Does the webhook say why a monitor is down?
Yes. data.failure_reason carries a short reason such as HTTP 503 Service Unavailable on down, recovered, reminder, escalation and acknowledged events. It is null when unknown.
Can webhooks go to an internal URL?
No. The webhook URL must be a publicly reachable HTTPS endpoint. Private and internal addresses are refused.
Why did I receive the same event twice?
A retry can repeat an event if your acknowledgement was lost. Use the event id (also in X-Monitoring-Event-ID) to ignore duplicates.