Get updates via webhook

What are Webhook Subscriptions?

Webhook subscriptions allow you to receive automated HTTP POST requests whenever there's a status update on the services you're monitoring. Instead of constantly polling for changes, we'll push updates directly to your specified endpoint.

Example Payloads

Incident Update

{
  "event_type": "incident",
  "meta": {
    "unsubscribe": "https://status.example.com/unsubscribe/abc123",
    "documentation": "https://docs.betteruptime.com/webhooks"
  },
  "page": {
    "id": "12345",
    "status_indicator": "downtime",
    "status_description": "Some services are down"
  },
  "incident": {
    "id": "98765",
    "name": "Database Connection Issues",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T11:45:00Z",
    "shortlink": "https://status.example.com/incidents/98765",
    "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": "2024-01-15T11:45:00Z",
        "updated_at": "2024-01-15T11:45:00Z"
      },
      {
        "id": "11110",
        "status_report_id": "98765",
        "body": "We're investigating connection issues with the database",
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
}

Maintenance Update

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

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] (incident, maintenance, or component_update)

Timeouts

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

Expected Response

We consider any 2xx HTTP status code as successful. Your endpoint should respond within 30 seconds.

Retry Policy

If your webhook fails, we'll automatically retry with exponential backoff:

• 1st retry: after 30 seconds
• 2nd retry: after 1 minute
• 3rd retry: after 2 minutes
• ...continuing up to 10 retries

After 10 failed attempts, we'll:

1. Deactivate the webhook
2. Send an email notification about the failure
3. Stop sending updates until you reactivate the subscription

Status Indicators

The status_indicator field can have these values:

• operational - Everything is working normally
• degraded - Some services experiencing issues
• downtime - Major service disruption
• maintenance - Scheduled maintenance in progress

Best Practices

1. Respond quickly - Return a 2xx status as soon as you've received the payload
2. Process asynchronously - Don't do heavy processing before responding
3. Monitor failures - Keep an eye on the failure notification emails

Getting Started

To set up a webhook subscription:

1. Go to your status page
2. Click "Get updates"
3. Select "Webhook" as the subscription type
4. Enter your endpoint URL
5. Provide your email for confirmation and failure notifications
6. Check your email and confirm the subscription
7. Start receiving real-time updates!

That's it! Your webhook is now ready to receive status updates. If you have any questions or run into issues, our support team is here to help.