Open-source status page, incident response and uptime monitoring
TypeScript alertingincident-managementmcpmcp-servermonitoringmonitoring-as-codeobservabilityon-callopen-sourcesrestatus-pagestatuspagesynthetic-monitoringterraformtinybirdtursouptimeuptime-checkeruptime-monitor
chore: statuspage socials notifier (#2317)
Maximilian Kaske1e95ec4bcfb5
diff --git a/apps/web/public/assets/changelog/status-page-socials-notifier.png b/apps/web/public/assets/changelog/status-page-socials-notifier.pngnew file mode 100644index 000000000..43761b9fdBinary files /dev/null and b/apps/web/public/assets/changelog/status-page-socials-notifier.png differdiff --git a/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/bsky-settings-create-app-success.png b/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/bsky-settings-create-app-success.pngnew file mode 100644index 000000000..7aeded129Binary files /dev/null and b/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/bsky-settings-create-app-success.png differdiff --git a/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/bsky-settings-create-app.png b/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/bsky-settings-create-app.pngnew file mode 100644index 000000000..83864e9c9Binary files /dev/null and b/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/bsky-settings-create-app.png differdiff --git a/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/bsky-settings-security.png b/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/bsky-settings-security.pngnew file mode 100644index 000000000..0dd97526bBinary files /dev/null and b/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/bsky-settings-security.png differdiff --git a/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/bsky-settings.png b/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/bsky-settings.pngnew file mode 100644index 000000000..c4a9a3e3cBinary files /dev/null and b/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/bsky-settings.png differdiff --git a/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/openstatus-subscribers-webhook.png b/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/openstatus-subscribers-webhook.pngnew file mode 100644index 000000000..8c5d6c49aBinary files /dev/null and b/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/openstatus-subscribers-webhook.png differdiff --git a/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/x-developer-console-app-oauth-key-success.png b/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/x-developer-console-app-oauth-key-success.pngnew file mode 100644index 000000000..9d8ac1a53Binary files /dev/null and b/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/x-developer-console-app-oauth-key-success.png differdiff --git a/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/x-developer-console-app-oauth-key.png b/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/x-developer-console-app-oauth-key.pngnew file mode 100644index 000000000..4cf4dd998Binary files /dev/null and b/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/x-developer-console-app-oauth-key.png differdiff --git a/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/x-developer-console-apps.png b/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/x-developer-console-apps.pngnew file mode 100644index 000000000..185bb49fcBinary files /dev/null and b/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/x-developer-console-apps.png differdiff --git a/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/x-developer-console-create-app-success.png b/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/x-developer-console-create-app-success.pngnew file mode 100644index 000000000..32c713f7dBinary files /dev/null and b/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/x-developer-console-create-app-success.png differdiff --git a/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/x-developer-console-create-app.png b/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/x-developer-console-create-app.pngnew file mode 100644index 000000000..374e6fbecBinary files /dev/null and b/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/x-developer-console-create-app.png differdiff --git a/apps/web/src/content/docs.config.ts b/apps/web/src/content/docs.config.tsindex 01703c2b3..cb3e3112b 100644--- a/apps/web/src/content/docs.config.ts+++ b/apps/web/src/content/docs.config.ts@@ -148,6 +148,10 @@ export const docsNav: DocsNavSection[] = [slug: "guides/how-to-setup-slack-agent",label: "How to Set Up the openstatus Slack Agent",},+ {+ slug: "guides/how-to-deploy-statuspage-socials-notifier",+ label: "How to Auto-Post Status Updates to X and Bluesky",+ },{slug: "guides/how-to-connect-openstatus-to-claude-code",label: "How to Connect openstatus to Claude Code",diff --git a/apps/web/src/content/pages/changelog/status-page-socials-notifier.mdx b/apps/web/src/content/pages/changelog/status-page-socials-notifier.mdxnew file mode 100644index 000000000..adf02d6ad--- /dev/null+++ b/apps/web/src/content/pages/changelog/status-page-socials-notifier.mdx@@ -0,0 +1,16 @@+---+title: "Auto-post status updates to X and Bluesky"+description: "Cross-post your status page updates to X and Bluesky with the statuspage-socials-notifier."+image: "/assets/changelog/status-page-socials-notifier.png"+publishedAt: "2026-06-29"+category: "statuspage"+author: "openstatus"+---++When you publish a status report or schedule maintenance, you often want to announce it on social media too — without copy-pasting the same message into each app.++[`statuspage-socials-notifier`](https://github.com/openstatusHQ/statuspage-socials-notifier) is a small open-source service that receives your status page's webhook payload and cross-posts each update to your X (formerly Twitter) and Bluesky accounts.++Add it as a webhook subscriber on your status page, deploy it to Vercel, Fly.io, or Railway, and it does the rest.++Follow the [guide](https://www.openstatus.dev/docs/guides/how-to-deploy-statuspage-socials-notifier) to set it up.diff --git a/apps/web/src/content/pages/docs/guides/how-to-deploy-statuspage-socials-notifier.mdx b/apps/web/src/content/pages/docs/guides/how-to-deploy-statuspage-socials-notifier.mdxnew file mode 100644index 000000000..4b2b421ed--- /dev/null+++ b/apps/web/src/content/pages/docs/guides/how-to-deploy-statuspage-socials-notifier.mdx@@ -0,0 +1,174 @@+---+category: Guides+title: How to Auto-Post Status Updates to X and Bluesky+description: A step-by-step guide to deploying the statuspage-socials-notifier and cross-posting your status page updates to X (Twitter) and Bluesky.+---++## Problem++When you publish a status report or schedule maintenance, you also want to announce it on X (formerly Twitter) and Bluesky — without copy-pasting the same message into each app every time.++## Solution++[`statuspage-socials-notifier`](https://github.com/openstatusHQ/statuspage-socials-notifier) is a small open-source [Hono](https://hono.dev) service that receives the openstatus webhook payload and cross-posts each update to your X and Bluesky accounts. You add it as a [webhook subscriber](/docs/reference/subscriber#webhook-subscribers) on your status page, and it does the rest.++This guide walks through collecting the credentials it needs and deploying it.++## Prerequisites++- An openstatus account with a configured status page.+- An [X developer account](https://developer.x.com) with write access.+- A [Bluesky account](https://bsky.app).+- A deploy target — this guide uses [Vercel](https://vercel.com); [Fly.io](https://fly.io) and [Railway](https://railway.com) are also supported.++## Environment variables++The service is configured entirely through environment variables.++| Variable | Required | Purpose |+| --- | --- | --- |+| `OPENSTATUS_WEBHOOK_TOKEN` | No | Shared secret the webhook must send as `Authorization: Bearer <token>`. |+| `BLUESKY_IDENTIFIER` | No | Your Bluesky handle or email (e.g. `acme.bsky.social`). |+| `BLUESKY_APP_PASSWORD` | No | A Bluesky App Password (not your account password). |+| `X_API_KEY` | No | X app API key (OAuth 1.0a). |+| `X_API_SECRET` | No | X app API secret. |+| `X_ACCESS_TOKEN` | No | X user access token. |+| `X_ACCESS_SECRET` | No | X user access token secret. |+| `POST_ON_STATUSES` | No | Comma-separated statuses to post on (e.g. `investigating,resolved`). Defaults to all. |+| `POST_MAINTENANCE` | No | Set to `true` to also post scheduled maintenance. |+| `PORT` | No | Server port. Defaults to `3000` (ignored on serverless platforms). |++## Step-by-step guide++### 1. Generate a webhook token++Pick any sufficiently random string — this is the shared secret between openstatus and your service. It is not required but recommended to keep the endpoint authenticated. For example:++```bash+openssl rand -hex 32+```++Save it as `OPENSTATUS_WEBHOOK_TOKEN`. You'll reuse the same value when you create the subscriber in step 5.++### 2. Create a Bluesky App Password++App Passwords let an app post on your behalf without exposing your real password.++1. In Bluesky, open **Settings**.++<Image+ src="/docs/guides/how-to-deploy-statuspage-socials-notifier/bsky-settings.png"+ alt="Bluesky settings menu"+/>++2. Go to **Privacy and Security** and click **App passwords**.++<Image+ src="/docs/guides/how-to-deploy-statuspage-socials-notifier/bsky-settings-security.png"+ alt="Bluesky Privacy and Security settings"+/>++3. Click **Add App Password** and give it a name (e.g. `openstatus-notifier`).++<Image+ src="/docs/guides/how-to-deploy-statuspage-socials-notifier/bsky-settings-create-app.png"+ alt="Naming a new Bluesky App Password"+/>++4. Copy the generated password — Bluesky won't show it again.++<Image+ src="/docs/guides/how-to-deploy-statuspage-socials-notifier/bsky-settings-create-app-success.png"+ alt="The generated Bluesky App Password"+/>++Set `BLUESKY_IDENTIFIER` to your handle (e.g. `acme.bsky.social`) and `BLUESKY_APP_PASSWORD` to the value you just copied.++### 3. Create an X app and access tokens++1. Open the [X Developer Portal](https://developer.x.com) and go to **Apps**.++<Image+ src="/docs/guides/how-to-deploy-statuspage-socials-notifier/x-developer-console-apps.png"+ alt="X Developer Console apps list"+/>++2. Click **Create App**, give it a name, and pick an environment.++<Image+ src="/docs/guides/how-to-deploy-statuspage-socials-notifier/x-developer-console-create-app.png"+ alt="Creating a new X client application"+/>++3. On creation, X shows your **Consumer Key** and **Secret Key** once — copy them to `X_API_KEY` and `X_API_SECRET`.++<Image+ src="/docs/guides/how-to-deploy-statuspage-socials-notifier/x-developer-console-create-app-success.png"+ alt="X application created with consumer and secret keys"+/>++4. Open the app's **Keys & Tokens** tab. Under **User authentication settings**, enable **OAuth 1.0a** with **Read and write** permissions, then generate an **Access Token and Secret**.++<Image+ src="/docs/guides/how-to-deploy-statuspage-socials-notifier/x-developer-console-app-oauth-key.png"+ alt="X app keys and tokens with OAuth 1.0a access token"+/>++5. Copy the **Access Token** and **Access Token Secret** to `X_ACCESS_TOKEN` and `X_ACCESS_SECRET` — they're shown only once.++<Image+ src="/docs/guides/how-to-deploy-statuspage-socials-notifier/x-developer-console-app-oauth-key-success.png"+ alt="X access token and secret generated"+/>++Make sure the access token is generated **after** you set Read and write permissions — otherwise posts will fail with a permissions error.++### 4. Deploy the service++Fork or clone the [repository](https://github.com/openstatusHQ/statuspage-socials-notifier), then deploy it to your platform of choice.++#### Vercel++1. In Vercel, click **Add New → Project** and import your fork.+2. Add every variable from the table above under **Settings → Environment Variables**.+3. Click **Deploy**. Your webhook endpoint will be available at `https://<your-project>.vercel.app/webhook`.++#### Fly.io++The repo ships a preconfigured `fly.toml`. Set each variable as a secret, then deploy:++```bash+fly secrets set OPENSTATUS_WEBHOOK_TOKEN=... BLUESKY_IDENTIFIER=... BLUESKY_APP_PASSWORD=... \+ X_API_KEY=... X_API_SECRET=... X_ACCESS_TOKEN=... X_ACCESS_SECRET=...+fly deploy+```++#### Railway++Import the repo (Railway auto-detects the Dockerfile) and add the environment variables in the project dashboard.++> These platforms scale to zero, so the first request after an idle period incurs a ~1–2s cold start. That fits inside openstatus' 5s webhook timeout, and failed deliveries are retried up to 3 times with exponential backoff — so a cold start may delay, but won't drop, the first post.++### 5. Add the webhook subscriber in openstatus++1. In the dashboard, open your status page and go to **Subscribers**.+2. Add a subscriber with channel **Webhook** and set the URL to your deployed endpoint, e.g. `https://<your-project-url>/webhook`.+3. Add a request header `Authorization` with value `Bearer <OPENSTATUS_WEBHOOK_TOKEN>` (the token from step 1).++<Image+ src="/docs/guides/how-to-deploy-statuspage-socials-notifier/openstatus-subscribers-webhook.png"+ alt="Adding a webhook subscriber with URL and Authorization header in openstatus"+/>++Because the destination isn't a Slack or Discord URL, openstatus sends the [generic JSON payload](/docs/reference/subscriber#generic), which the notifier knows how to parse.++### 6. Test it++Use the subscriber's **Send test** action to verify connectivity — openstatus delivers a `type: "test"` payload, which the notifier ignores (it only posts real events), so check your service logs for the received request rather than your social accounts.++To verify end-to-end posting, publish a status report on your page. Within a couple of seconds you should see the update appear on both your X and Bluesky accounts.++## Related resources++- **[Subscriber reference](/docs/reference/subscriber)** — how subscribers and webhook payloads work.+- **[statuspage-socials-notifier](https://github.com/openstatusHQ/statuspage-socials-notifier)** — source code and configuration reference.diff --git a/apps/web/src/content/pages/docs/reference/subscriber.mdx b/apps/web/src/content/pages/docs/reference/subscriber.mdxindex cfe556e8a..d9bea51a0 100644--- a/apps/web/src/content/pages/docs/reference/subscriber.mdx+++ b/apps/web/src/content/pages/docs/reference/subscriber.mdx@@ -37,6 +37,206 @@ Status page administrators can manage their subscriber lists, including:- **Adding/removing subscribers** — manually adding or removing subscribers.- **Communication** — sending ad-hoc notifications to the subscriber list (if supported by the platform).+## Adding subscribers from the dashboard++Beyond public self-subscription, administrators can add subscribers directly from the dashboard. This is useful for onboarding partners, internal teams, or automation that should receive updates without going through the public opt-in flow. Each manually added subscriber uses one of two channels:++- **Email** — delivers updates to a contact address. By adding an email here you confirm the contact has consented to receive status updates; no confirmation email is sent.+- **Webhook** — POSTs each update to a URL. Slack and Discord URLs receive channel-native messages; any other URL receives a generic JSON payload.++For both channels, you can optionally:++- **Set a display label** — shown in place of the raw destination in the dashboard (e.g. `Supabase #incidents`).+- **Scope to page components** — leave empty to notify for the entire page, or select specific components to only notify on matching reports.++++## Webhook subscribers++A webhook subscriber receives a POST request for every status report and scheduled maintenance update. openstatus inspects the destination URL and emits a payload tailored to it.++### Slack++A URL starting with `https://hooks.slack.com/services/` is treated as a Slack incoming webhook. The payload uses Slack [Block Kit](https://api.slack.com/block-kit) attachments — a colored header (red/yellow/green/blue by status), status and page fields, the update message, affected components, and footer links to view, manage, and unsubscribe.++### Discord++A URL starting with `https://discord.com/api/webhooks/` is treated as a Discord webhook. The payload uses a Discord embed with a status-colored sidebar, a title linking to the event, status and page fields, the update message, affected components, and manage/unsubscribe links.++### Generic++Any other URL receives a versioned, channel-agnostic JSON payload. Use this to forward updates into your own systems. The body is shaped as:++```json+{+ "version": "1",+ "type": "status_report",+ "data": {+ "status_report": {+ "id": 123,+ "title": "Database connectivity issues",+ "url": "https://acme.openstatus.dev/events/report/123",+ "update": {+ "id": 456,+ "status": "investigating",+ "message": "We are investigating elevated error rates.",+ "occurred_at": "2026-06-26T10:00:00.000Z"+ },+ "page": {+ "id": 1,+ "name": "Acme Status",+ "slug": "acme",+ "url": "https://acme.openstatus.dev"+ },+ "components": [+ { "id": 7, "name": "API", "impact": "major_outage" }+ ]+ }+ },+ "subscription": {+ "manage_url": "https://acme.openstatus.dev/manage/<token>",+ "unsubscribe_url": "https://acme.openstatus.dev/unsubscribe/<token>"+ }+}+```++`page.url` is the canonical status page origin, while `status_report.url` (and `maintenance.url` below) is the deep link to that specific event. Each entry in `components` carries an `impact`, which may be `null` when no impact is associated with the component for this update.++Scheduled maintenance is delivered with `type: "maintenance"` and a `data.maintenance` object carrying `starts_at` / `ends_at` in place of the `update` block. The `version` field is bumped on any breaking change, so pin to it when consuming the payload.++The **Send test** action emits the same envelope with `type: "test"` and a `data.test` object — use the `type` discriminator to ignore it (it carries no real event):++```json+{+ "version": "1",+ "type": "test",+ "data": {+ "test": {+ "message": "Your openstatus webhook is configured correctly.",+ "timestamp": "2026-06-26T10:38:00.132Z"+ }+ }+}+```++You can attach **custom request headers** to every webhook request — for example, a shared secret or an authorization token your receiver verifies.++#### Timeout and retries++Each webhook request is given **5 seconds** to complete. If your endpoint has not responded within that window, the request is aborted and treated as a failed attempt.++Failed attempts are retried with **jittered exponential backoff** (≈200 ms base delay), up to **3 retries** (4 attempts total). Only transient failures are retried:++- **Network errors and timeouts** (no HTTP response).+- **`5xx` responses** — a server-side error on your end that may clear.+- **`429 Too Many Requests`** — your endpoint asked us to back off.++Any other `4xx` response (e.g. `400`, `401`, `404`) is treated as a permanent client error and is **not** retried, since replaying the same request would fail again. Make your receiver **idempotent** — a retried delivery is identical to the original, so deduplicate on the update `id` if you act on each request.++#### Example: post updates to X / Bluesky++[`statuspage-socials-notifier`](https://github.com/openstatusHQ/statuspage-socials-notifier) is a reference receiver that consumes the generic payload and cross-posts each update to your X (Twitter) and Bluesky accounts. Point a generic webhook subscriber at its endpoint to mirror your status page on social media — it doubles as a worked example of validating and handling the payload.++#### Validating the payload++The payload shape is defined in [`packages/subscriptions/src/payload.ts`](https://github.com/openstatusHQ/openstatus/blob/main/packages/subscriptions/src/payload.ts). Copy this zod schema to validate incoming requests in your own receiver:++```ts+import { z } from "zod";++export const WEBHOOK_PAYLOAD_VERSION = "1" as const;++const impactSchema = z.enum([+ "operational",+ "degraded_performance",+ "partial_outage",+ "major_outage",+]);++const statusSchema = z.enum([+ "investigating",+ "identified",+ "monitoring",+ "resolved",+]);++const componentSchema = z.object({+ id: z.number().int(),+ name: z.string(),+ impact: impactSchema.nullish(),+});++const pageSchema = z.object({+ id: z.number().int(),+ name: z.string(),+ slug: z.string(),+ url: z.url(),+});++const subscriptionSchema = z.object({+ manage_url: z.string().nullish(),+ unsubscribe_url: z.string().nullish(),+});++const statusReportWebhookSchema = z.object({+ version: z.literal(WEBHOOK_PAYLOAD_VERSION),+ type: z.literal("status_report"),+ data: z.object({+ status_report: z.object({+ id: z.number().int(),+ title: z.string(),+ url: z.url(),+ update: z.object({+ id: z.number().int(),+ status: statusSchema,+ message: z.string(),+ occurred_at: z.string(),+ }),+ page: pageSchema,+ components: z.array(componentSchema),+ }),+ }),+ subscription: subscriptionSchema,+});++const maintenanceWebhookSchema = z.object({+ version: z.literal(WEBHOOK_PAYLOAD_VERSION),+ type: z.literal("maintenance"),+ data: z.object({+ maintenance: z.object({+ id: z.number().int(),+ title: z.string(),+ url: z.url(),+ message: z.string(),+ starts_at: z.string().optional(),+ ends_at: z.string().optional(),+ page: pageSchema,+ components: z.array(componentSchema),+ }),+ }),+ subscription: subscriptionSchema,+});++const testWebhookSchema = z.object({+ version: z.literal(WEBHOOK_PAYLOAD_VERSION),+ type: z.literal("test"),+ data: z.object({+ test: z.object({+ message: z.string(),+ timestamp: z.string(),+ }),+ }),+});++export const webhookPayloadSchema = z.discriminatedUnion("type", [+ statusReportWebhookSchema,+ maintenanceWebhookSchema,+ testWebhookSchema,+]);++export type WebhookPayload = z.infer<typeof webhookPayloadSchema>;+```+## Related resources- **[Status page reference](/docs/reference/status-page)** — detailed information on managing and configuring status pages.