Skip to main content

Notifications

Notifications have two parts:
  1. Channels are reusable destinations (email, Slack, Discord, Telegram) that receive alerts. They belong to your account.
  2. Schedule preferences decide which outcomes (failure, success, both, or none) notify you for a given schedule and which channels receive them.
A channel must be verified before it can be attached to a schedule.
Available channel types and notification options depend on your plan. Requests that exceed a plan limit return a PLAN_LIMIT_EXCEEDED error.

Channels

List channels

Returns: Promise<NotificationChannel[]> (secrets are never included)

Create a channel

The config shape depends on type.
Returns: Promise<NotificationChannel> (unverified until you verify it)

Verify a channel

Sends a test notification and marks the channel verified on success.
Returns: Promise<NotificationChannel>

Get, update, and delete

The channel type is immutable. Changing the delivery destination (for example a new webhook URL or email address) resets the channel to unverified, so call verifyNotificationChannel again before it can send. A label-only change keeps its verified status. Deleting a channel automatically detaches it from any schedule preferences that referenced it.

Schedule preferences

Get a schedule’s preference

Returns: Promise<ScheduleNotificationPreference> (unset schedules return notifyOn: "none" with no channels)

Set a schedule’s preference

Returns: Promise<ScheduleNotificationPreference> Rules enforced by the API:
  • channelIds is required (non-empty) when notifyOn is not "none".
  • Every channel id must reference a verified channel you own.
  • success and both require at least one webhook channel (Slack, Discord, or Telegram); email is not delivered per success.
  • Some notifyOn values are gated by plan.
The returned preference may include a non-blocking warning (for example, when enabling per-success notifications on a very high-frequency schedule).

Example: alert on failures