Webhooks Guide
Real-time monitoring for zero-downtime SaaS
Configuring Webhook Endpoints
Connect StatusPulse to your internal tools or incident management platforms by configuring HTTPS endpoints that accept POST requests.
1. Generate a Secret Key
Navigate to Project Settings > Integrations > Webhooks. Click "Create Endpoint" to generate a unique `sp_wh_` secret key. Store this securely; it will be used to verify request signatures.
2. Define Trigger Events
Select which monitoring events fire your webhook. Options include `check.down`, `check.up`, `ssl.expiring_soon`, and `metric.threshold_exceeded`. You can map multiple checks to a single endpoint.
3. Validate Endpoint Reachability
StatusPulse sends a `ping.test` payload to your URL. Your server must respond with a `2xx` status code within 5 seconds. If validation fails, the webhook remains in `disabled` state until corrected.
Payload Structure & Signature Verification
Every webhook delivery contains a JSON body and an `X-StatusPulse-Signature` header for security.
The JSON payload follows a consistent schema. For a `check.down` event on the `api.production.statuspulse.io` endpoint, the body looks like this:
{"event": "check.down", "check_id": "chk_8829471", "target": "api.production.statuspulse.io", "region": "us-east-1", "status_code": 502, "response_time_ms": 12405, "timestamp": "2024-05-14T09:23:11Z", "metadata": {"last_known_up": "2024-05-14T09:22:58Z", "error_type": "bad_gateway"}}
To verify authenticity, compute an HMAC-SHA256 hash of the raw request body using your secret key. Compare the result against the hex-encoded value in the `X-StatusPulse-Signature` header. Mismatched signatures indicate a tampered or spoofed request.
Retry Logic & Delivery Guarantees
StatusPulse uses an exponential backoff strategy to handle transient network failures without overwhelming your infrastructure.
Initial Retry Window
If your endpoint returns a `5xx` error or times out, StatusPulse retries immediately, then at 30 seconds, 2 minutes, and 8 minutes. Successful `2xx` or `3xx` responses halt the retry cycle.
Backoff & Dead Letter Queue
After the initial window, retries occur at 30-minute intervals for up to 24 hours. Payloads that fail all delivery attempts are moved to the Dead Letter Queue, accessible via the StatusPulse dashboard for manual replay or archival.
Idempotency & Duplicates
Each payload includes a unique `request_id` field. Design your consumers to be idempotent by tracking these IDs. StatusPulse may deliver a duplicate payload if a network timeout occurs before your server sends a response, even if the request succeeded.
Need to adjust delivery frequency or configure custom headers? Contact our engineering team at integrations@statuspulse.io to enable advanced routing for enterprise accounts.