Webhook subscriptions

Get an HTTP POST request on your endpoint whenever there's a status update on the services you follow.

Subscribe with webhooks

1. On the status page you want to follow, click Get updates.
2. On the Webhook tab, enter your endpoint URL.
3. Enter your e-mail address. It receives the confirmation e-mail and failure notifications.
4. To follow only some components, check Subscribe to specific components and select them.
5. Click Subscribe, then click Confirm your subscription in the e-mail.

Your webhook starts receiving updates right after confirmation.

Example payloads

Every request shares the same meta and page objects. The event_type field tells you which event was delivered and which event-specific object follows:

{
  "event_type": "incident",
  "meta": {
    "unsubscribe": "https://status.example.com/unsubscribe-webhook/abc123",
    "documentation": "https://betterstack.com/docs/uptime/subscribing-to-status-updates/subscribing-with-webhooks/"
  },
  "page": {
    "id": 12345,
    "status_indicator": "downtime",
    "status_description": "Some services are down"
  },
  "incident": {
    "id": 98765,
    "name": "Database connection issues",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T11:45:00Z",
    "shortlink": "https://status.example.com/98765/incidents",
    "organization_id": 12345,
    "incident_updates": [
      {
        "id": 11111,
        "status_report_id": 98765,
        "body": "We've identified the issue and are working on a fix.",
        "created_at": "2026-01-15T11:45:00Z",
        "updated_at": "2026-01-15T11:45:00Z"
      },
      {
        "id": 11110,
        "status_report_id": 98765,
        "body": "We're investigating connection issues with the database.",
        "created_at": "2026-01-15T10:30:00Z",
        "updated_at": "2026-01-15T10:30:00Z"
      }
    ]
  }
}

{
  "event_type": "maintenance",
  "meta": {
    "unsubscribe": "https://status.example.com/unsubscribe-webhook/abc123",
    "documentation": "https://betterstack.com/docs/uptime/subscribing-to-status-updates/subscribing-with-webhooks/"
  },
  "page": {
    "id": 12345,
    "status_indicator": "maintenance",
    "status_description": "Ongoing maintenance"
  },
  "maintenance": {
    "id": 87654,
    "name": "Scheduled database upgrade",
    "created_at": "2026-01-14T09:00:00Z",
    "updated_at": "2026-01-15T02:00:00Z",
    "starts_at": "2026-01-15T02:00:00Z",
    "ends_at": "2026-01-15T04:00:00Z",
    "shortlink": "https://status.example.com/87654/incidents",
    "organization_id": 12345,
    "maintenance_updates": [
      {
        "id": 22222,
        "status_report_id": 87654,
        "body": "Database upgrade scheduled for tonight.",
        "created_at": "2026-01-14T09:00:00Z",
        "updated_at": "2026-01-14T09:00:00Z"
      }
    ]
  }
}

{
  "event_type": "component_update",
  "meta": {
    "unsubscribe": "https://status.example.com/unsubscribe-webhook/abc123",
    "documentation": "https://betterstack.com/docs/uptime/subscribing-to-status-updates/subscribing-with-webhooks/"
  },
  "page": {
    "id": 12345,
    "status_indicator": "degraded",
    "status_description": "Some services are degraded"
  },
  "component_update": {
    "id": "a1b2c3d4e5f60718293a4b5c",
    "created_at": "2026-01-15T12:00:00Z",
    "old_status": "operational",
    "new_status": "degraded",
    "component_id": 55555
  },
  "component": {
    "id": 55555,
    "name": "API Gateway",
    "status": "degraded",
    "created_at": "2025-11-02T08:15:00Z"
  }
}

Payload structure

Shared objects

Every payload includes meta and page.

Meta

• unsubscribe: Link that stops this webhook subscription.
• documentation: Link to this page.

Page

• id: Numeric identifier of the status page.
• status_indicator: Overall status of the page, one of operational, degraded, downtime, or maintenance.
• status_description: Human-readable summary of status_indicator.

The status_indicator and status_description values always pair up as follows:

Event types

The event_type field determines which event-specific object is present:

• incident: New incident or an update to an existing incident.
  Payload carries an incident object.
• maintenance: Scheduled maintenance window or an update to one.
  Payload carries a maintenance object.
• component_update: Monitored component changed status.
  Payload carries component_update and component objects.

Incident and maintenance objects

Both objects share the same fields. Maintenance adds starts_at and ends_at, and names its updates array maintenance_updates.

• id: Numeric identifier of the incident or maintenance.
• name: Title shown on the status page.
• created_at / updated_at: ISO 8601 timestamps.
• starts_at / ends_at: Scheduled window for maintenance only.
• shortlink: Public link to the incident on the status page.
• organization_id: Identifier of the status page the incident belongs to, matches page.id.
• incident_updates or maintenance_updates: Array of updates, newest first. Each entry contains:
  • id: Numeric identifier of the update.
  • status_report_id: Identifier of the parent incident or maintenance.
  • body: Update message text.
  • created_at / updated_at: ISO 8601 timestamps.

Component updates and component objects

The component_update describes the change:

• id: Unique identifier for this change event.
• created_at: ISO 8601 timestamp of the change.
• old_status: Previous status, set to resolved when the previous status wasn't tracked.
• new_status: Status the component changed to.
• component_id: Numeric identifier of the component, matches component.id.

The component describes the component's current state:

• id: Numeric identifier of the component.
• name: Public name of the component.
• status: Current status, matching new_status.
• created_at: ISO 8601 timestamp of when the component was created.

Component statuses use the same values as page.status_indicator: operational, degraded, downtime, and maintenance.

HTTP request details

Headers

Every webhook request includes these headers:

• Content-Type: application/json
• User-Agent: BetterStack-StatusPage/1.0
• X-BetterUptime-Event: [event_type]
  Event type is either incident, maintenance, or component_update.

Request format

All webhooks use HTTP POST with JSON payloads. Requests are sent with:

• UTF-8 encoding
• JSON content type

Timeouts

• Connection timeout: 10 seconds
• Request timeout: 30 seconds

Your endpoint must respond within 30 seconds or the request is considered failed.

Expected response

We consider any 2xx HTTP status code as successful. Your endpoint should:

• Return 200 OK, 201 Created, or 204 No Content
• Respond within 30 seconds
• Not require authentication headers. Use URL-based auth if needed

Redirects

Webhooks do not follow HTTP redirects. Make sure your endpoint URL returns a direct 2xx response.

Retry policy

If your webhook fails, Better Stack retries it up to 10 times with exponential backoff, about 8.5 hours in total.

After failed retries

After 10 failed retries, Better Stack will:

1. Deactivate the webhook subscription
2. Send an e-mail notification to your contact e-mail about the failure
3. Stop sending updates until you reactivate the subscription

Reactivating after failure

To reactivate a deactivated webhook:

1. Fix the endpoint issue causing failures.
2. Visit the status page and subscribe again with the same endpoint URL.
3. Confirm the subscription via e-mail.

Resubscribing with the same URL resets the failure count and requires a fresh e-mail confirmation.

Troubleshooting

Webhook not receiving requests

1. Verify the subscription was confirmed via e-mail.
2. Check the endpoint URL is correct and reachable.
3. Ensure the endpoint returns a 2xx status within 30 seconds.
4. Confirm your firewall allows traffic from Better Stack.
5. For an https:// endpoint, check its SSL certificate is valid.

Requests timing out

1. Move processing to a background queue.
2. Return a 2xx response immediately after receiving the payload.
3. Check network latency to your endpoint.

Need help?

Please let us know at hello@betterstack.com. We're happy to help! 🙏