Webhooks Integration

Webhooks provide the most flexible way to integrate StatusPageOne with your custom systems and workflows. When monitors detect issues or recover, StatusPageOne can send HTTP POST requests to your specified endpoints with detailed payload information.

Key Benefits

Real-time notifications - Instant HTTP POST requests when events occur
Custom processing - Build any workflow around the webhook data
Rich payloads - Detailed monitor and check result information
Reliable delivery - Automatic retries with exponential backoff
Secure - Optional webhook signature validation

Quick Setup

Step 1: Prepare Your Webhook Endpoint

Create an HTTP endpoint that can receive POST requests:

Example Webhook Handler (Node.js):

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhooks/statuspageone', (req, res) => {
  const { event_type, monitor, check_result, context } = req.body;

  console.log('Received alert:', {
    monitor: monitor.name,
    status: check_result.status,
    timestamp: check_result.timestamp
  });

  // Your custom logic here
  if (check_result.status === 'DOWN') {
    handleIncident(monitor, check_result);
  } else {
    handleRecovery(monitor, check_result);
  }

  // Always respond with 200 to acknowledge receipt
  res.status(200).json({ received: true });
});

function handleIncident(monitor, result) {
  // Create incident ticket
  // Send escalated alerts
  // Update status dashboard
}

function handleRecovery(monitor, result) {
  // Close incident ticket
  // Notify team of recovery
  // Update metrics
}

app.listen(3000, () => {
  console.log('Webhook server listening on port 3000');
});

Step 2: Configure in StatusPageOne

Access Integration Settings
- Navigate to your status page
- Click "Integrations" in the sidebar
- Select "Webhooks" from the integration list
Add Webhook URL
- Enter your webhook endpoint URL
- Choose which events to receive (incidents, recoveries, or both)
- Configure retry settings if needed
Test Connection
- Use the "Test Webhook" button
- Verify your endpoint receives and processes the test payload
- Check StatusPageOne logs for delivery confirmation

Webhook Payload Structure

StatusPageOne sends detailed JSON payloads to your webhook endpoints:

Incident Alert Payload

🚨 Incident Alert Payload:

{
  "event_type": "monitor_alert",
  "monitor": {
    "id": "mon_abc123xyz789",
    "name": "API Server",
    "url": "https://api.example.com/health",
    "status": "DOWN"
  },
  "check_result": {
    "status": "DOWN",
    "timestamp": "2024-01-15T10:30:15Z",
    "region": "us-east-1",
    "error_message": "Connection timeout after 30 seconds",
    "response_time_ms": 30000,
    "status_code": null
  },
  "context": {
    "consecutive_failures": 3,
    "previous_status": "UP",
    "notification_level": 1,
    "notification_type": "incident"
  }
}

Recovery Alert Payload

✅ Recovery Alert Payload:

{
  "event_type": "monitor_alert",
  "monitor": {
    "id": "mon_abc123xyz789",
    "name": "API Server",
    "url": "https://api.example.com/health",
    "status": "UP"
  },
  "check_result": {
    "status": "UP",
    "timestamp": "2024-01-15T10:42:30Z",
    "region": "us-east-1",
    "response_time_ms": 245,
    "status_code": 200
  },
  "context": {
    "consecutive_failures": 0,
    "previous_status": "DOWN",
    "notification_level": 1,
    "notification_type": "recovery"
  }
}

Common Use Cases

Incident Management Integration

JIRA Ticket Creation:

async function createJiraTicket(monitor, checkResult) {
  const jiraPayload = {
    fields: {
      project: { key: 'OPS' },
      summary: `[INCIDENT] ${monitor.name} is DOWN`,
      description: `
        Monitor: ${monitor.name}
        URL: ${monitor.url}
        Error: ${checkResult.error_message}
        Region: ${checkResult.region}
        Time: ${checkResult.timestamp}
      `,
      issuetype: { name: 'Incident' },
      priority: { name: 'High' }
    }
  };

  const response = await fetch('https://your-domain.atlassian.net/rest/api/3/issue', {
    method: 'POST',
    headers: {
      'Authorization': `Basic ${btoa('email:token')}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(jiraPayload)
  });

  const ticket = await response.json();
  console.log('Created JIRA ticket:', ticket.key);
}

Custom Dashboard Updates

Real-time Status Dashboard:

// Update internal status dashboard
app.post('/webhooks/statuspageone', async (req, res) => {
  const { monitor, check_result } = req.body;

  // Update database
  await updateServiceStatus({
    serviceId: monitor.id,
    status: check_result.status,
    lastCheck: check_result.timestamp,
    responseTime: check_result.response_time_ms,
    errorMessage: check_result.error_message
  });

  // Broadcast to websocket clients
  io.emit('service-update', {
    serviceId: monitor.id,
    serviceName: monitor.name,
    status: check_result.status,
    timestamp: check_result.timestamp
  });

  res.status(200).json({ received: true });
});

Slack Escalation Workflow

Automated Slack Escalation:

async function handleEscalation(monitor, checkResult) {
  const { consecutive_failures, notification_level } = checkResult.context;

  // Escalate after 3 failures
  if (consecutive_failures >= 3) {
    await sendSlackMessage({
      channel: '#critical-alerts',
      text: `🚨 ESCALATION: ${monitor.name} has failed ${consecutive_failures} times`,
      mentions: ['@oncall-engineer', '@ops-manager']
    });
  }

  // Page on-call after 5 failures
  if (consecutive_failures >= 5) {
    await triggerPagerDuty({
      incident_key: `monitor-${monitor.id}`,
      description: `Critical: ${monitor.name} - ${checkResult.error_message}`,
      service_key: 'your-pagerduty-service-key'
    });
  }
}

Database Logging

Incident Analytics & Logging:

async function logIncidentData(webhookPayload) {
  const { monitor, check_result, context } = webhookPayload;

  const incident = {
    monitor_id: monitor.id,
    monitor_name: monitor.name,
    monitor_url: monitor.url,
    status: check_result.status,
    timestamp: new Date(check_result.timestamp),
    region: check_result.region,
    response_time: check_result.response_time_ms,
    status_code: check_result.status_code,
    error_message: check_result.error_message,
    consecutive_failures: context.consecutive_failures,
    notification_level: context.notification_level
  };

  await database.incidents.create(incident);

  // Update metrics
  await updateSLAMetrics(monitor.id, incident);
}

Security & Validation

Webhook Signature Validation

Validate webhook authenticity:

const crypto = require('crypto');

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

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

app.post('/webhooks/statuspageone', (req, res) => {
  const signature = req.headers['x-statuspageone-signature'];
  const payload = JSON.stringify(req.body);

  if (!validateWebhook(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process verified webhook
  handleWebhook(req.body);
  res.status(200).json({ received: true });
});

Best Practices

Error Handling

Always respond with 200: Acknowledge receipt even if processing fails
Implement retries: Handle temporary failures in your processing logic
Log webhook data: Keep records for debugging and analytics
Validate payloads: Check required fields before processing

Performance Optimization

Async processing: Don't block webhook response for long operations
Queue heavy tasks: Use background jobs for time-intensive operations
Monitor webhook performance: Track response times and failure rates
Implement timeouts: Set reasonable timeouts for external calls

Security Considerations

Use HTTPS: Always use secure endpoints for webhook URLs
Validate signatures: Implement webhook signature verification
Rate limiting: Protect your endpoints from abuse
Input validation: Sanitize and validate all incoming data

Troubleshooting

Common Issues

Webhook not receiving data:

Verify URL accessibility from external networks
Check firewall and security group settings
Ensure endpoint accepts POST requests
Validate Content-Type handling

Delivery failures:

Check StatusPageOne integration logs
Verify your endpoint returns 200 status codes
Implement proper error handling
Monitor webhook response times

Payload issues:

Validate JSON parsing in your handler
Check for required field handling
Implement schema validation
Log received payloads for debugging

Testing Tools

Use curl to test your endpoint:

curl -X POST https://your-domain.com/webhooks/statuspageone \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "monitor_alert",
    "monitor": {"id": "test", "name": "Test Monitor"},
    "check_result": {"status": "DOWN", "timestamp": "2024-01-15T10:30:15Z"}
  }'

Webhook testing services:

Use tools like ngrok for local development
Consider webhook.site for quick testing
Implement health check endpoints

Rate Limits

Delivery rate: Up to 100 webhooks per minute per integration
Retry attempts: Up to 5 retries with exponential backoff
Timeout: 30-second timeout per webhook request
Payload size: Maximum 1MB per payload

Need help with webhook integration? Check our API documentation or contact support.

Webhooks Integration

Key Benefits

Real-time notifications - Instant HTTP POST requests when events occur
Custom processing - Build any workflow around the webhook data
Rich payloads - Detailed monitor and check result information
Reliable delivery - Automatic retries with exponential backoff
Secure - Optional webhook signature validation

Quick Setup

Step 1: Prepare Your Webhook Endpoint

Create an HTTP endpoint that can receive POST requests:

Example Webhook Handler (Node.js):

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhooks/statuspageone', (req, res) => {
  const { event_type, monitor, check_result, context } = req.body;

  console.log('Received alert:', {
    monitor: monitor.name,
    status: check_result.status,
    timestamp: check_result.timestamp
  });

  // Your custom logic here
  if (check_result.status === 'DOWN') {
    handleIncident(monitor, check_result);
  } else {
    handleRecovery(monitor, check_result);
  }

  // Always respond with 200 to acknowledge receipt
  res.status(200).json({ received: true });
});

function handleIncident(monitor, result) {
  // Create incident ticket
  // Send escalated alerts
  // Update status dashboard
}

function handleRecovery(monitor, result) {
  // Close incident ticket
  // Notify team of recovery
  // Update metrics
}

app.listen(3000, () => {
  console.log('Webhook server listening on port 3000');
});

Step 2: Configure in StatusPageOne

Access Integration Settings
- Navigate to your status page
- Click "Integrations" in the sidebar
- Select "Webhooks" from the integration list
Add Webhook URL
- Enter your webhook endpoint URL
- Choose which events to receive (incidents, recoveries, or both)
- Configure retry settings if needed
Test Connection
- Use the "Test Webhook" button
- Verify your endpoint receives and processes the test payload
- Check StatusPageOne logs for delivery confirmation

Webhook Payload Structure

StatusPageOne sends detailed JSON payloads to your webhook endpoints:

Incident Alert Payload

🚨 Incident Alert Payload:

{
  "event_type": "monitor_alert",
  "monitor": {
    "id": "mon_abc123xyz789",
    "name": "API Server",
    "url": "https://api.example.com/health",
    "status": "DOWN"
  },
  "check_result": {
    "status": "DOWN",
    "timestamp": "2024-01-15T10:30:15Z",
    "region": "us-east-1",
    "error_message": "Connection timeout after 30 seconds",
    "response_time_ms": 30000,
    "status_code": null
  },
  "context": {
    "consecutive_failures": 3,
    "previous_status": "UP",
    "notification_level": 1,
    "notification_type": "incident"
  }
}

Recovery Alert Payload

✅ Recovery Alert Payload:

{
  "event_type": "monitor_alert",
  "monitor": {
    "id": "mon_abc123xyz789",
    "name": "API Server",
    "url": "https://api.example.com/health",
    "status": "UP"
  },
  "check_result": {
    "status": "UP",
    "timestamp": "2024-01-15T10:42:30Z",
    "region": "us-east-1",
    "response_time_ms": 245,
    "status_code": 200
  },
  "context": {
    "consecutive_failures": 0,
    "previous_status": "DOWN",
    "notification_level": 1,
    "notification_type": "recovery"
  }
}

Common Use Cases

Incident Management Integration

JIRA Ticket Creation:

async function createJiraTicket(monitor, checkResult) {
  const jiraPayload = {
    fields: {
      project: { key: 'OPS' },
      summary: `[INCIDENT] ${monitor.name} is DOWN`,
      description: `
        Monitor: ${monitor.name}
        URL: ${monitor.url}
        Error: ${checkResult.error_message}
        Region: ${checkResult.region}
        Time: ${checkResult.timestamp}
      `,
      issuetype: { name: 'Incident' },
      priority: { name: 'High' }
    }
  };

  const response = await fetch('https://your-domain.atlassian.net/rest/api/3/issue', {
    method: 'POST',
    headers: {
      'Authorization': `Basic ${btoa('email:token')}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(jiraPayload)
  });

  const ticket = await response.json();
  console.log('Created JIRA ticket:', ticket.key);
}

Custom Dashboard Updates

Real-time Status Dashboard:

// Update internal status dashboard
app.post('/webhooks/statuspageone', async (req, res) => {
  const { monitor, check_result } = req.body;

  // Update database
  await updateServiceStatus({
    serviceId: monitor.id,
    status: check_result.status,
    lastCheck: check_result.timestamp,
    responseTime: check_result.response_time_ms,
    errorMessage: check_result.error_message
  });

  // Broadcast to websocket clients
  io.emit('service-update', {
    serviceId: monitor.id,
    serviceName: monitor.name,
    status: check_result.status,
    timestamp: check_result.timestamp
  });

  res.status(200).json({ received: true });
});

Slack Escalation Workflow

Automated Slack Escalation:

async function handleEscalation(monitor, checkResult) {
  const { consecutive_failures, notification_level } = checkResult.context;

  // Escalate after 3 failures
  if (consecutive_failures >= 3) {
    await sendSlackMessage({
      channel: '#critical-alerts',
      text: `🚨 ESCALATION: ${monitor.name} has failed ${consecutive_failures} times`,
      mentions: ['@oncall-engineer', '@ops-manager']
    });
  }

  // Page on-call after 5 failures
  if (consecutive_failures >= 5) {
    await triggerPagerDuty({
      incident_key: `monitor-${monitor.id}`,
      description: `Critical: ${monitor.name} - ${checkResult.error_message}`,
      service_key: 'your-pagerduty-service-key'
    });
  }
}

Database Logging

Incident Analytics & Logging:

async function logIncidentData(webhookPayload) {
  const { monitor, check_result, context } = webhookPayload;

  const incident = {
    monitor_id: monitor.id,
    monitor_name: monitor.name,
    monitor_url: monitor.url,
    status: check_result.status,
    timestamp: new Date(check_result.timestamp),
    region: check_result.region,
    response_time: check_result.response_time_ms,
    status_code: check_result.status_code,
    error_message: check_result.error_message,
    consecutive_failures: context.consecutive_failures,
    notification_level: context.notification_level
  };

  await database.incidents.create(incident);

  // Update metrics
  await updateSLAMetrics(monitor.id, incident);
}

Security & Validation

Webhook Signature Validation

Validate webhook authenticity:

const crypto = require('crypto');

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

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

app.post('/webhooks/statuspageone', (req, res) => {
  const signature = req.headers['x-statuspageone-signature'];
  const payload = JSON.stringify(req.body);

  if (!validateWebhook(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process verified webhook
  handleWebhook(req.body);
  res.status(200).json({ received: true });
});

Best Practices

Error Handling

Always respond with 200: Acknowledge receipt even if processing fails
Implement retries: Handle temporary failures in your processing logic
Log webhook data: Keep records for debugging and analytics
Validate payloads: Check required fields before processing

Performance Optimization

Async processing: Don't block webhook response for long operations
Queue heavy tasks: Use background jobs for time-intensive operations
Monitor webhook performance: Track response times and failure rates
Implement timeouts: Set reasonable timeouts for external calls

Security Considerations

Use HTTPS: Always use secure endpoints for webhook URLs
Validate signatures: Implement webhook signature verification
Rate limiting: Protect your endpoints from abuse
Input validation: Sanitize and validate all incoming data

Troubleshooting

Common Issues

Webhook not receiving data:

Verify URL accessibility from external networks
Check firewall and security group settings
Ensure endpoint accepts POST requests
Validate Content-Type handling

Delivery failures:

Check StatusPageOne integration logs
Verify your endpoint returns 200 status codes
Implement proper error handling
Monitor webhook response times

Payload issues:

Validate JSON parsing in your handler
Check for required field handling
Implement schema validation
Log received payloads for debugging

Testing Tools

Use curl to test your endpoint:

curl -X POST https://your-domain.com/webhooks/statuspageone \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "monitor_alert",
    "monitor": {"id": "test", "name": "Test Monitor"},
    "check_result": {"status": "DOWN", "timestamp": "2024-01-15T10:30:15Z"}
  }'

Webhook testing services:

Use tools like ngrok for local development
Consider webhook.site for quick testing
Implement health check endpoints

Rate Limits

Delivery rate: Up to 100 webhooks per minute per integration
Retry attempts: Up to 5 retries with exponential backoff
Timeout: 30-second timeout per webhook request
Payload size: Maximum 1MB per payload

Need help with webhook integration? Check our API documentation or contact support.

Webhooks Integration

Webhooks Integration

Key Benefits

Quick Setup

Step 1: Prepare Your Webhook Endpoint

Step 2: Configure in StatusPageOne

Webhook Payload Structure

Incident Alert Payload

Recovery Alert Payload

Common Use Cases

Incident Management Integration

Custom Dashboard Updates

Slack Escalation Workflow

Database Logging

Security & Validation

Webhook Signature Validation

Best Practices

Error Handling

Performance Optimization

Security Considerations

Troubleshooting

Common Issues

Testing Tools

Rate Limits

Improve this page

Webhooks Integration

Webhooks Integration

Key Benefits

Quick Setup

Step 1: Prepare Your Webhook Endpoint

Step 2: Configure in StatusPageOne

Webhook Payload Structure

Incident Alert Payload

Recovery Alert Payload

Common Use Cases

Incident Management Integration

Custom Dashboard Updates

Slack Escalation Workflow

Database Logging

Security & Validation

Webhook Signature Validation

Best Practices

Error Handling

Performance Optimization

Security Considerations

Troubleshooting

Common Issues

Testing Tools

Rate Limits

Improve this page