Webhook notifications

A webhook channel sends each alert as JSON to a URL you control.

Adding a webhook

1. Open Settings → Notification Channels, click Add Channel and select Webhook.
2. Enter the URL and choose the method: POST (default), PUT or PATCH.
3. Optionally add headers, one Name: value per line, for example an Authorization header.
4. Optionally enter a signing secret.
5. Save, then click Send Test.

The URL must use http:// or https:// and resolve to a public address; private and internal addresses are refused. Use HTTPS so the payload is encrypted in transit. Only the standard ports 80 and 443 are allowed. Redirects are followed only to the same scheme, host and port, and a 303 redirect is refused.

Payloads

Every request has Content-Type: application/json.

Site down:

{
  "event": "site_down",
  "timestamp": "2026-02-07T15:45:00+00:00",
  "site": { "id": 12, "name": "My Website", "url": "https://example.com" },
  "incident": { "id": 345, "started_at": "2026-02-07T15:44:10+00:00", "reason": "Connection timed out" }
}

Site recovered (event is site_up): the incident object contains id, started_at, resolved_at, duration_seconds and formatted_duration.

TLS, DNS and scan events (ssl_expiring, ssl_renewed, dns_changed, dns_restored, scan_issue, scan_resolved) contain event, site, data (event details), message (a readable summary) and timestamp.

Test messages have event set to test, a message and the channel id and name.

Webhook channels do not receive performance alerts.

Verifying the signature

When a signing secret is set, each request carries an X-Webhook-Signature header. Its value is the lowercase hex HMAC-SHA256 of the raw request body, keyed with your secret. There is no prefix.

$body = file_get_contents('php://input');
$expected = hash_hmac('sha256', $body, getenv('UPTIMEVANGUARD_WEBHOOK_SECRET'));

if (! hash_equals($expected, $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}

Compute the HMAC over the bytes you received, before any JSON parsing.

Responses and retries

Return any 2xx status. Other statuses, connection failures and timeouts count as failed deliveries. The connection timeout is 5 seconds and the request timeout is 10 seconds. Failed deliveries are retried automatically as described in Notification channels, so make your endpoint idempotent, for example by using the incident id and event name.