Custom Webhooks

Send HTTP POST requests to any endpoint when status page events occur. Perfect for integrating with custom applications, automation workflows, or third-party services.

Overview

Custom webhooks allow you to send event notifications to any HTTP endpoint. Unlike Discord webhooks which use a specific format, custom webhooks send a standard JSON payload that you can parse and handle in your own applications.

Creating a Webhook

1. Navigate to Admin → Notifications
2. Click Add Notification
3. Select Webhook as the type
4. Enter a descriptive name
5. Enter your webhook URL
6. Optionally add a webhook secret for signature verification
7. Select which events should trigger the webhook
8. Click Save

Payload Format

Webhooks send a JSON payload with the following structure:

{
  "event": "incident.created",
  "timestamp": "2026-01-14T12:00:00Z",
  "statusPage": {
    "id": 1,
    "name": "Main Status",
    "slug": "main"
  },
  "data": {
    // Event-specific data
  }
}

Incident Events

For incident events, the data object contains:

{
  "event": "incident.created",
  "data": {
    "id": 123,
    "title": "API Connectivity Issues",
    "status": "investigating",
    "severity": "major",
    "message": "We are investigating reports of API errors.",
    "components": ["API", "Dashboard"],
    "startedAt": "2026-01-14T12:00:00Z"
  }
}

Maintenance Events

{
  "event": "maintenance.scheduled",
  "data": {
    "id": 45,
    "title": "Database Maintenance",
    "message": "Scheduled database maintenance window.",
    "components": ["Database"],
    "windowStart": "2026-01-15T02:00:00Z",
    "windowEnd": "2026-01-15T04:00:00Z"
  }
}

Component Events

{
  "event": "component.status_changed",
  "data": {
    "id": 5,
    "name": "API Gateway",
    "previousStatus": "operational",
    "newStatus": "degraded",
    "uptimePercent": 99.5
  }
}

Available Event Types

Signature Verification

For security, you can add a webhook secret. When set, all webhook requests include an X-Webhook-Signature header containing an HMAC-SHA256 signature of the payload.

Verifying the Signature

// Node.js example
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

HTTP Request Details

Request Headers

Content-Type: application/json
User-Agent: ATStatus-Webhook/1.0
X-Webhook-Event: incident.created
X-Webhook-Signature: (HMAC signature if secret configured)
X-Request-ID: (unique request identifier)

Best Practices

• Respond Quickly: Return a 2xx response within 10 seconds. Process the webhook asynchronously if needed.
• Handle Duplicates: Use the X-Request-ID header to detect and handle duplicate deliveries.
• Verify Signatures: Always verify the webhook signature in production environments.
• Use HTTPS: Only use HTTPS endpoints to protect payload data in transit.