Skip to main content

Overview

Webhooks allow you to integrate StatusStack with any service that accepts HTTP webhooks, including PagerDuty, Datadog, custom systems, and more.

Setup Guide

1

Get Webhook URL

From your target service:
  • PagerDuty: Events API v2 endpoint
  • Datadog: Webhook integration URL
  • Custom: Your webhook endpoint
2

Configure in StatusStack

  1. SettingsNotifications
  2. Create rule
  3. Select Webhook channel
  4. Enter webhook URL
  5. Add custom headers (optional)
  6. Select HTTP method (POST default)
3

Test

Send test webhook

Webhook Payload

StatusStack sends JSON payloads:
{
  "event": "component.status_changed",
  "timestamp": "2025-01-19T10:30:00Z",
  "stack": {
    "id": "stack_abc123",
    "name": "Production Infrastructure",
    "slug": "production"
  },
  "component": {
    "id": "comp_xyz789",
    "name": "Production API",
    "previous_status": "operational",
    "current_status": "critical"
  },
  "incident": {
    "id": "inc_123",
    "created_at": "2025-01-19T10:30:00Z"
  }
}

Security

Webhook Signatures

StatusStack signs webhooks with HMAC-SHA256:
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}
Signature sent in X-StatusStack-Signature header.

Common Integrations

PagerDuty

Webhook URL: https://events.pagerduty.com/v2/enqueue
Headers:
  Authorization: Token token=your-integration-key
  Content-Type: application/json

Payload mapping:
  - event_action: trigger/acknowledge/resolve
  - severity: critical/error/warning/info
  - summary: Component status message

Datadog

Webhook URL: https://api.datadoghq.com/api/v1/events
Headers:
  DD-API-KEY: your-api-key
  Content-Type: application/json

Custom Endpoint

// Your webhook receiver
app.post('/webhooks/statusstack', (req, res) => {
  const { event, stack, component } = req.body;
  
  // Verify signature
  if (!verifyWebhook(req.body, req.headers['x-statusstack-signature'])) {
    return res.status(401).send('Invalid signature');
  }
  
  // Handle event
  if (event === 'component.status_changed') {
    // Create alert in your system
    createAlert(component);
  }
  
  res.status(200).send('OK');
});

Event Types

StatusStack sends these event types:
  • component.status_changed
  • monitor.down
  • monitor.recovered
  • incident.created
  • incident.updated
  • incident.resolved
  • maintenance.scheduled
Filter events in notification rule settings.

Best Practices

  • Verify signatures to prevent spoofing
  • Return 200 OK quickly (< 5 seconds)
  • Process asynchronously for heavy operations
  • Handle retries gracefully (idempotent)
  • Log failures for debugging

Troubleshooting

Webhook Failing

Check:
  1. URL is publicly accessible (HTTPS required)
  2. Endpoint returns 200 OK
  3. No firewall blocking StatusStack IPs
  4. Signature verification (if enabled)

Delayed Delivery

Causes:
  • Your endpoint is slow (> 5 seconds)
  • Rate limiting
  • Network issues
Solutions:
  • Return 200 immediately, process async
  • Increase timeout settings
  • Check endpoint logs

Next Steps

Notification Setup

Configure notification rules