Webhooks Configuration
Real-time uptime monitoring for everyone
Payload Format
SitePulse delivers webhook notifications as standard JSON payloads over HTTPS POST requests. Every event includes a consistent schema so you can parse alerts, status changes, and scheduled reports without conditional branching.
Each payload contains a top-level event_type string, a unique webhook_id, and a monitor object with operational metadata. Response times are reported in milliseconds, and timestamps follow ISO 8601 UTC format.
Incident Notification
{
"event_type": "monitor.down",
"webhook_id": "wh_8f3a9c2d1e",
"monitor": {
"id": "mon_48291",
"name": "api.example.com",
"status": "down",
"last_check": "2024-06-12T14:22:07Z",
"response_time_ms": 0,
"region": "us-east-1"
}
}
Service Restored
{
"event_type": "monitor.up",
"webhook_id": "wh_8f3a9c2d1e",
"monitor": {
"id": "mon_48291",
"name": "api.example.com",
"status": "up",
"last_check": "2024-06-12T14:28:41Z",
"response_time_ms": 142,
"region": "us-east-1"
}
}
Security Signatures
Every webhook request includes an HMAC-SHA256 signature in the X-SitePulse-Signature header. Verify this signature before processing the payload to ensure the request originated from SitePulse and was not tampered with in transit.
The signature is generated by hashing the raw request body using your webhook secret key. The resulting hash is base64-encoded and prefixed with a timestamp window to prevent replay attacks. Rotate your secret key instantly from the dashboard if it is ever compromised.
Extract Header & Body
Capture the X-SitePulse-Signature header value and the raw POST body. Do not parse or modify the body before verification, as whitespace changes will invalidate the hash.
Compute HMAC
Use your webhook secret as the HMAC key and SHA-256 as the algorithm. Compare the computed hash against the received signature using a constant-time comparison function to prevent timing attacks.
Validate Timestamp
Check the X-SitePulse-Timestamp header against your server clock. Reject requests older than 300 seconds to mitigate replay attempts and ensure event freshness.
Retry Logic
SitePulse automatically retries failed webhook deliveries using an exponential backoff schedule. If your endpoint returns a non-2xx status code or fails to respond within 10 seconds, the system queues the event for redelivery.
Retries occur at 30-second, 2-minute, 10-minute, 30-minute, and 2-hour intervals before marking the webhook as failed. You can view delivery logs, inspect HTTP response codes, and trigger manual retries directly from the monitoring dashboard.
Automatic Redelivery
Attempts 1–5 follow a strict exponential curve. If your server consistently returns 429 Too Many Requests, SitePulse extends the interval up to 4 hours and pauses further retries until you acknowledge the backlog.
HTTP Status Validation
Only 200–299 responses are treated as successful. 3xx redirects are not followed, and 4xx/5xx errors trigger the retry queue. Ensure your endpoint returns a valid 2xx status even if you process the payload asynchronously.
Failed Event Archive
After exhausting all retries, failed payloads are stored in your account's dead-letter queue for 30 days. You can export these events as JSON, update your endpoint URL, and retrigger delivery without losing historical data.