Webhooks & Alerting

The One Status sends outbound webhooks when incidents, maintenance, and component status changes occur. Use webhooks to integrate with Slack, Microsoft Teams, PagerDuty, your PSA, or any HTTP endpoint.

Outbound Webhooks

Creating a Webhook

1. Open the status page and click the Webhooks tab
2. Click Add Webhook
3. Configure:

Field	Description
URL	The endpoint that will receive the POST request
Events	Which event types to send (see event types below)
Format	Payload format — JSON (default)

4. Click Save
5. Click Test to send a sample payload and confirm your endpoint receives it

Webhook Events

Event	When It Fires
incident.created	A new incident is declared
incident.updated	An incident update is posted (status change or message)
incident.resolved	An incident is marked resolved
component.status_changed	A component's status changes (manual or automated)
maintenance.scheduled	A maintenance window is scheduled
maintenance.started	A maintenance window begins (auto or manual)
maintenance.completed	A maintenance window ends (auto or manual)

You can subscribe a single webhook to all events or a subset. Create multiple webhooks to route different event types to different systems.

Webhook Payload Format

All webhooks send a JSON POST with the following structure:

{
  "event": "incident.created",
  "timestamp": "2026-03-09T14:05:00.000Z",
  "page": {
    "id": "page-abc123",
    "name": "Acme IT Services Status",
    "subdomain": "acme"
  },
  "data": {
    "id": "inc-xyz789",
    "title": "Help Desk Ticket Submission Disrupted",
    "status": "investigating",
    "impact": "major",
    "affected_components": ["comp-001"],
    "started_at": "2026-03-09T14:00:00.000Z",
    "created_at": "2026-03-09T14:05:00.000Z"
  }
}

For component.status_changed events, the data includes component_id, component_name, previous_status, and new_status.

Webhook Signature Verification

Every webhook request includes an X-TheOneStatus-Signature header for authenticity verification. The signature format is:

t=1709990700,v1=abc123def456...

Where:

• t is the Unix timestamp (seconds)
• v1 is an HMAC-SHA256 signature of {timestamp}.{body} using your webhook secret

Verifying the signature (Node.js example):

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const parts = signature.split(',');
  const timestamp = parts.find(p => p.startsWith('t=')).slice(2);
  const received = parts.find(p => p.startsWith('v1=')).slice(3);

  const signedPayload = `${timestamp}.${payload}`;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(received, 'hex'),
    Buffer.from(expected, 'hex')
  );
}

Always verify webhook signatures in production to prevent spoofed requests.

Rotating the Webhook Secret

If a webhook secret is compromised or you need to rotate it:

1. In the Webhooks tab, click the webhook
2. Click Rotate Secret
3. Copy the new secret immediately — it is shown once

⚠️After rotating the secret, update your receiving endpoint immediately. Webhooks sent after rotation will fail verification with the old secret.

Webhook Delivery Log

Click any webhook in the Webhooks tab to view its delivery history:

• Timestamp of each delivery attempt
• HTTP response code from your endpoint
• Success or failure status

Use this to troubleshoot failed deliveries without needing to check your own server logs.

Integrating with Slack

Use a Slack Incoming Webhook URL as the webhook endpoint:

1. In Slack: Apps → Incoming WebHooks → Add to Slack → choose a channel → copy the Webhook URL
2. In The One Status: create a webhook with that URL, select the events you want in Slack
3. Test it — a JSON payload will appear in your Slack channel

ℹ️Slack's incoming webhook format expects Slack-specific JSON. The One Status sends standard JSON. Use a middleware service (e.g., Zapier, Make, or a small Azure Function) to transform the payload into Slack's block format for formatted messages.

Integrating with Microsoft Teams

Use Teams' Incoming Webhook connector:

1. In Teams: channel settings → Connectors → Incoming Webhook → copy the URL
2. Create a webhook in The One Status pointing to that URL
3. Use a middleware function to format the payload as an Adaptive Card for richer Teams messages

Integrating with PagerDuty

PagerDuty's Events API v2 accepts HTTP POST webhooks. Map The One Status events:

• incident.created → PagerDuty trigger event
• incident.resolved → PagerDuty resolve event

Use a small function or Zapier to transform the payload format.

API Keys

The One Status provides API keys for programmatic access to the management API (creating incidents, updating component statuses, etc.). This enables automated incident creation from external monitoring tools.

Creating an API Key

1. Navigate to Settings → Security (or the API Keys section)
2. Click Create API Key
3. Give it a descriptive name (e.g., "UptimeRobot Integration")
4. Copy the key immediately — it is shown only once

Using the API Key

Include the key in the Authorization header:

Authorization: Bearer your-api-key-here

Use the key to create incidents programmatically when your external monitoring tool detects a problem:

curl -X POST https://api.theonestatus.app/api/status-pages/{pageId}/incidents \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Website Down",
    "status": "investigating",
    "impact": "major",
    "affected_components": ["comp-001"],
    "message": "UptimeRobot detected the website is not responding."
  }'

Revoking an API Key

In Settings → Security, click Revoke next to the key. It stops working immediately.