Webhooks

Receive real-time notifications via HTTP POST when events occur. Integrate with any system that can receive webhooks.

Overview

Webhooks allow you to receive real-time HTTP POST notifications when events occur in Wakestack. Configure a webhook endpoint in your notification settings to receive events like monitor failures, recoveries, and incident updates.

Real-time Delivery

Events sent within seconds of occurrence

Signature Verification

HMAC signatures to verify authenticity

Event Types

Events that trigger webhook notifications

Event	Description
monitor.down	Monitor failed and hit alert threshold
monitor.up	Monitor recovered to operational
monitor.degraded	Monitor showing degraded performance
incident.created	New incident opened
incident.updated	Incident status changed
incident.resolved	Incident marked as resolved

Payload Structure

JSON payload sent to your webhook endpoint

Monitor Down Event

{
  "event": "monitor.down",
  "timestamp": "2024-01-15T10:30:00Z",
  "monitor": {
    "id": "mon_a1b2c3d4e5f6",
    "name": "API Health Check",
    "url": "https://api.example.com/health",
    "type": "http"
  },
  "incident": {
    "id": "inc_xyz789",
    "severity": "critical",
    "status": "investigating"
  },
  "details": {
    "consecutiveFailures": 3,
    "errorMessage": "Connection timeout after 30s",
    "responseTime": null,
    "statusCode": null,
    "region": "us-east"
  }
}

Monitor Up Event

{
  "event": "monitor.up",
  "timestamp": "2024-01-15T10:45:00Z",
  "monitor": {
    "id": "mon_a1b2c3d4e5f6",
    "name": "API Health Check",
    "url": "https://api.example.com/health",
    "type": "http"
  },
  "details": {
    "responseTime": 145,
    "statusCode": 200,
    "downtime": "15m",
    "region": "us-east"
  }
}

Incident Created Event

{
  "event": "incident.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "incident": {
    "id": "inc_xyz789",
    "title": "API Service Degradation",
    "description": "Multiple monitors reporting failures",
    "status": "investigating",
    "severity": "major",
    "affectedMonitors": ["mon_a1b2c3d4e5f6", "mon_g7h8i9j0"]
  }
}

HTTP Headers

Headers included with each webhook request

POST /your-webhook-endpoint HTTP/1.1
Host: your-server.com
Content-Type: application/json
User-Agent: Wakestack-Webhook/1.0
X-Wakestack-Event: monitor.down
X-Wakestack-Signature: sha256=abc123...
X-Wakestack-Timestamp: 1705312200
X-Wakestack-Delivery-Id: del_abc123

Header	Description
X-Wakestack-Event	Event type that triggered the webhook
X-Wakestack-Signature	HMAC-SHA256 signature for verification
X-Wakestack-Timestamp	Unix timestamp when event occurred
X-Wakestack-Delivery-Id	Unique ID for this delivery attempt

Signature Verification

Verify webhook authenticity using HMAC signatures

Each webhook includes a signature in the X-Wakestack-Signature header. Verify this signature to ensure the webhook came from Wakestack.

Node.js Example

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return `sha256=${expectedSignature}` === signature;
}

// In your webhook handler:
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-wakestack-signature'];
  const isValid = verifyWebhook(
    JSON.stringify(req.body),
    signature,
    process.env.WAKESTACK_WEBHOOK_SECRET
  );

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Process the webhook...
  res.status(200).send('OK');
});

Python Example

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return f"sha256={expected}" == signature

# In your Flask handler:
@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Wakestack-Signature')
    is_valid = verify_webhook(
        request.data.decode(),
        signature,
        os.environ['WAKESTACK_WEBHOOK_SECRET']
    )

    if not is_valid:
        return 'Invalid signature', 401

    # Process the webhook...
    return 'OK', 200

Retry Policy

How Wakestack handles failed webhook deliveries

If your endpoint returns a non-2xx status code or times out, Wakestack will retry the webhook:

Retry 1: After 1 minute
Retry 2: After 5 minutes
Retry 3: After 30 minutes
Retry 4: After 2 hours
Retry 5: After 24 hours

After 5 failed attempts, the webhook is marked as failed. You can view failed deliveries in your dashboard.

Best Practices

Respond Quickly

Return 200 immediately, process async. Timeout is 30 seconds.

Verify Signatures

Always verify the HMAC signature before processing.

Handle Duplicates

Use delivery ID to deduplicate in case of retries.

Use HTTPS

Always use HTTPS endpoints for security.

Related Resources

Setting Up Alerts

Configure notifications

Incidents API

Manage incidents

Notification Settings

Add webhook URL