Notifications

Slack, Discord, signed webhooks and email channels, and the events they receive.

Send monitoring and incident updates to Slack, Discord, email or your own webhook. Add channels under notifications and use events to choose what each one receives. The default failureThreshold of 3 means a monitor alerts on its third consecutive failed check, not on every failure.

import { discord, email, slack, webhook } from "@heyo-sh/heyo-status/notifications";notifications: {  failureThreshold: 3,  channels: [    slack({ webhookUrl: process.env.SLACK_WEBHOOK_URL!, mentionOnCritical: "<!here>" }),    discord({ webhookUrl: process.env.DISCORD_WEBHOOK_URL!, mentionRole: "ops" }),    webhook({ url: "https://ops.acme.com/hooks/status", secret: process.env.HOOK_SECRET! }),    email({      transport: "resend",      apiKey: process.env.RESEND_API_KEY!,      from: "status@acme.com",      to: ["oncall@acme.com"],    }),  ],},

failureThresholdnumberoptional

Defaults to 3. A monitor.down event fires on the check run where the consecutive-failure count reaches this number — not before and not again. The matching monitor.recovered fires once afterwards.

channelsNotificationChannel[]optional

Defaults to []. Channel ids must be unique.

Choose which events to send

Event	Raised when
`monitor.down`	A monitor's consecutive failures reach `failureThreshold`.
`monitor.recovered`	A monitor succeeds after a threshold-reaching outage.
`ssl.expiring`	An SSL monitor fails only because of an approaching expiry.
`incident.created`	An incident is opened manually or automatically.
`incident.updated`	A timeline entry is added, or the incident is edited.
`incident.resolved`	An incident reaches `resolved`.
`maintenance.scheduled`	A window is created or edited while `scheduled`.
`maintenance.starting`	A window becomes `in-progress`.
`maintenance.completed`	A window becomes `completed`.

Every builder accepts an events array of selectors. Wildcards are expanded once, at construction, so the dispatcher only compares exact names:

slack({ webhookUrl, events: ["monitor.*", "incident.created", "incident.resolved"] });webhook({ url, secret, events: ["*"] });

Valid selectors are any event name, monitor.*, ssl.*, incident.*, maintenance.* and *. An empty array, a duplicate or an unknown selector throws. Omitting events subscribes the channel to everything.

Slack

slack({  id: "slack-ops",  webhookUrl: process.env.SLACK_WEBHOOK_URL!,  channel: "#status",  mentionOnCritical: "<!here> production incident",  includeLatency: true,  events: ["monitor.*", "incident.*"],});

webhookUrlstringrequired

Slack incoming-webhook URL.

idstringoptional

Defaults to "slack". Appears in the notification log.

channelstringoptional

Incoming-webhook channel override.

mentionOnCriticalstringoptional

Fallback text used only when the event belongs to a critical incident.

includeLatencybooleanoptional

Defaults to true. Adds the latency field to the Block Kit payload.

fetchNotificationFetchoptional

Injectable fetch, for tests or a proxy.

Slack messages include the check message, target, status, latency and consecutive-failure count. With siteUrl set, they also link back to the status page.

Discord

discord({  id: "discord-ops",  webhookUrl: process.env.DISCORD_WEBHOOK_URL!,  mentionRole: "1234567890",  events: ["incident.*", "maintenance.*"],});

mentionRole accepts a role ID (rendered as <@&id>), an existing <@&id> mention, or a plain name (rendered as @name). The payload is a single embed, coloured green for recoveries, red for failures and amber for everything else.

Signed webhooks

webhook({  id: "ops-bridge",  url: "https://ops.acme.com/hooks/status",  secret: process.env.HOOK_SECRET!,  headers: { "x-source": "heyo-status" },  retries: 3,  retryDelayMs: 250,});

urlstringrequired

HTTP(S) destination.

secretstringrequired

Shared secret used for the HMAC-SHA256 signature. Cannot be empty.

retriesnumberoptional

Defaults to 3 total attempts, between 1 and 10.

retryDelayMsnumberoptional

Defaults to 250, doubled on each retry.

headersRecord<string, string>optional

Extra request headers. content-type and the signature headers are always set by the channel.

Each request carries:

http

content-type: application/jsonx-heyo-timestamp: 1767225600x-heyo-signature: t=1767225600,v1=<hex HMAC-SHA256 of `${timestamp}.${body}`>

Verify it on the receiving side with the helper the package exports:

import { verifyWebhookSignature } from "@heyo-sh/heyo-status/notifications";const body = await request.text();const valid = await verifyWebhookSignature(  process.env.HOOK_SECRET!,  request.headers.get("x-heyo-signature") ?? "",  body,);

The payload is the stable JSON produced by toStatusEventPayload():

json

{  "event": "monitor.down",  "timestamp": "2026-01-01T00:05:00.000Z",  "monitor": {    "name": "API",    "type": "http",    "group": "API",    "target": "https://api.acme.com/health",    "status": false,    "message": "HTTP 503, expected 200",    "latencyMs": 142,    "consecutiveFailures": 3  }}

incident and maintenance objects are added for their respective events.

Email

email({  transport: "resend",  apiKey: process.env.RESEND_API_KEY!,  from: "status@acme.com",  to: ["oncall@acme.com", "sre@acme.com"],});

Transport	Requirements
`resend`	`apiKey`. Optional `endpoint` override.
`aws-ses`	`accessKeyId`, `secretAccessKey`, optional `region` (default `us-east-1`), `sessionToken`, `endpoint`. Requests are SigV4-signed in-process; no AWS SDK is bundled.
`cloudflare`	A `send` callback bound to your Email binding.
`smtp`	A `send` callback backed by your SMTP transport.

email({  transport: "cloudflare",  from: "status@acme.com",  to: "oncall@acme.com",  async send(message) {    await env.STATUS_EMAIL.send(new EmailMessage(message.from, message.to[0], message.text));  },});

An email channel is also what makes public email subscriptions possible: the first configured email channel exposes sendEmail(), which the subscription flow reuses for confirmation and incident mail. Without one, POST /subscribers with type: "email" answers 503.

Custom channels

Any object matching NotificationChannel is accepted:

import type { NotificationChannel } from "@heyo-sh/heyo-status/types";const pagerduty: NotificationChannel = {  id: "pagerduty",  type: "webhook",  events: ["monitor.down", "incident.created"],  async send(event) {    await fetch("https://events.pagerduty.com/v2/enqueue", {      method: "POST",      headers: { "content-type": "application/json" },      body: JSON.stringify({        routing_key: process.env.PD_ROUTING_KEY,        event_action: "trigger",        payload: {          summary: event.monitor?.message ?? event.incident?.title ?? event.type,          severity: "error",          source: event.monitor?.target ?? "heyo-status",        },      }),    });    return { attempts: 1 };  },};

type must be one of slack, discord, webhook or email — it classifies the row written to the notification log. Returning { attempts } records how many tries the delivery took.

What happens when delivery fails

Channel failures are isolated. A broken webhook never fails a check run, an incident update or an HTTP request.
Every attempt is written to notification_log with its channel, event, status, attempt count and error, readable via GET /admin/notifications/log.
Writing that log is itself best-effort: a logging failure is swallowed for the same reason.
Only the generic webhook channel retries. Slack, Discord and email report the first failure.