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.

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",
    },
  },
});