Skip to content

Open-source status page, incident response and uptime monitoring

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.png
new file mode 100644
index 000000000..43761b9fd
Binary files /dev/null and b/apps/web/public/assets/changelog/status-page-socials-notifier.png differ
diff --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.png
new file mode 100644
index 000000000..7aeded129
Binary files /dev/null and b/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/bsky-settings-create-app-success.png differ
diff --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.png
new file mode 100644
index 000000000..83864e9c9
Binary files /dev/null and b/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/bsky-settings-create-app.png differ
diff --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.png
new file mode 100644
index 000000000..0dd97526b
Binary files /dev/null and b/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/bsky-settings-security.png differ
diff --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.png
new file mode 100644
index 000000000..c4a9a3e3c
Binary files /dev/null and b/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/bsky-settings.png differ
diff --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.png
new file mode 100644
index 000000000..8c5d6c49a
Binary files /dev/null and b/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/openstatus-subscribers-webhook.png differ
diff --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.png
new file mode 100644
index 000000000..9d8ac1a53
Binary files /dev/null and b/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/x-developer-console-app-oauth-key-success.png differ
diff --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.png
new file mode 100644
index 000000000..4cf4dd998
Binary files /dev/null and b/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/x-developer-console-app-oauth-key.png differ
diff --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.png
new file mode 100644
index 000000000..185bb49fc
Binary files /dev/null and b/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/x-developer-console-apps.png differ
diff --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.png
new file mode 100644
index 000000000..32c713f7d
Binary files /dev/null and b/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/x-developer-console-create-app-success.png differ
diff --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.png
new file mode 100644
index 000000000..374e6fbec
Binary files /dev/null and b/apps/web/public/docs/guides/how-to-deploy-statuspage-socials-notifier/x-developer-console-create-app.png differ
diff --git a/apps/web/src/content/docs.config.ts b/apps/web/src/content/docs.config.ts
index 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.mdx
new file mode 100644
index 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.mdx
new file mode 100644
index 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.mdx
index 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.
+
+![openstatus](/assets/logos/openstatus.jpeg)
+
+## 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.