Relays Overview

Relays are alert routing pipelines. They receive alerts via webhooks and process them through ordered rules to notify people, call external APIs, or invoke AI agents.

Relay Rules

Each relay has rules that execute in order. Rule types:

• schedule_notify - Notify the on-call user from a schedule
• webhook - Call an external URL (Slack, PagerDuty, etc.)
• agent - Invoke an AI agent (Devin, Cursor Cloud Agent)

Rules are organized into groups. Rules in the same group run sequentially; rules in different groups run in parallel. See Best Practices for examples.

Timed Escalation

Every rule has a delayMinutes (0–1440, default 0): how long after the alert arrives before the rule fires. If the alert is acknowledged or resolved before a rule’s delay elapses, the rule is cancelled — so “notify primary now, secondary in 5 minutes” only beeps the secondary if nobody responded.

Relays also have a repeat policy that controls what happens when every rule has fired and the alert is still unacknowledged:

• none (default) — run the plan once and stop
• once — run the plan a second time, then stop
• all — keep repeating until the alert is acknowledged or resolved

Repeat cycles honor each rule’s delay, and a new cycle starts no sooner than 5 minutes after the previous cycle’s last rule.

const relay = await client.relay.create({
  name: "Production Alerts",
  externalKey: "production-relay",
  repeat: "all",
});

await client.relay.rules.create(relay.id, {
  name: "Notify primary",
  externalKey: "notify-primary",
  ruleType: "schedule_notify",
  config: { scheduleId: "sch_primary" },
});

await client.relay.rules.create(relay.id, {
  name: "Notify secondary",
  externalKey: "notify-secondary",
  ruleType: "schedule_notify",
  delayMinutes: 5,
  config: { scheduleId: "sch_secondary" },
});

Common Use Cases

Direct Schedule Notification

Route all alerts directly to your on-call schedule:

const relay = await client.relay.create({
  name: "Production Alerts",
  description: "Critical production incidents",
  externalKey: "production-relay", // Idempotent - safe to re-run
});

await client.relay.rules.create(relay.id, {
  name: "Notify on-call engineer",
  externalKey: "notify-oncall", // Idempotent rule creation
  ruleType: "schedule_notify",
  config: {
    scheduleId: "sch_xyz123",
  },
});

Escalation with AI Agent

Try an AI agent first, then escalate to humans:

await client.relay.rules.create(relay.id, {
  name: "Try AI agent first",
  externalKey: "agent-first", // Idempotent
  order: 1,
  ruleType: "agent",
  config: {
    agentType: "devin",
    integrationId: "int_abc123",
  },
});

await client.relay.rules.create(relay.id, {
  name: "Escalate to on-call",
  externalKey: "escalate-oncall", // Idempotent
  order: 2,
  ruleType: "schedule_notify",
  config: {
    scheduleId: "sch_xyz123",
  },
});

Webhook Integration

Send alerts to external systems:

await client.relay.rules.create(relay.id, {
  name: "Post to Slack",
  externalKey: "slack-webhook", // Idempotent
  ruleType: "webhook",
  config: {
    endpoint: "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    payload: {
      text: "New alert received",
    },
  },
});