Best Practices

Idempotent Configuration

Always set externalKey on relays, schedules, and relay rules. This makes operations idempotent—you can safely re-run setup scripts without creating duplicates.

// First run: creates relay
const relay = await client.relay.create({
  name: "Production Alerts",
  externalKey: "prod-alerts-v1",
});

// Second run: updates existing relay (no duplicate)
const sameRelay = await client.relay.create({
  name: "Production Alerts (Updated)",
  externalKey: "prod-alerts-v1", // Same key = update
});

Use a consistent naming convention for external keys:

// Recommended: namespace::resource::identifier
"myco::relay::production"
"myco::schedule::primary-weekly"
"myco::rule::notify-oncall"

Parallel vs Sequential Execution

The group field on relay rules controls execution flow:

• Same group = sequential (order 1, then 2, then 3)
• Different groups = parallel (run simultaneously)

// Parallel: AI and humans notified at the same time
{ group: "agents", order: 1, ruleType: "agent" }
{ group: "humans", order: 1, ruleType: "schedule_notify" }

// Sequential: AI tries first, then escalates to humans
{ group: "default", order: 1, ruleType: "agent" }
{ group: "default", order: 2, ruleType: "schedule_notify" }

Use parallel when: You want the fastest possible response time.

Use sequential when: You want AI to attempt resolution before interrupting humans.

Relays

• Descriptive names: Use names that indicate purpose (“Production Alerts”, not “Relay 1”)
• Separate by service: Create different relays for different services or environments
• Test rules disabled: Create rules with enabled: false, test, then enable

Schedules

• UTC times: All times are in UTC. Account for your team’s time zones when setting startTime
• Member order matters: Members rotate in the order they’re added
• Weekly over daily: Weekly rotations are generally better for work-life balance
• Always have coverage: Ensure your schedule has at least one member at all times

Contact Methods

• Multiple channels: Add both email and SMS for each on-call engineer
• E.164 format: Use international format for phone numbers (+14155551234)
• Verify methods: Verified contact methods have higher deliverability
• Keep updated: Review contact information when team members change roles

Agent Integrations

• Environment separation: Use separate integrations for dev/staging/prod
• Rotate keys regularly: Update API keys periodically for security
• Descriptive metadata: Store environment and purpose in metadata

Testing

1. Create relays and rules with enabled: false
2. Send test alerts to verify webhook connectivity
3. Use client.relay.simulate() to preview routing
4. Use client.relay.lint() to validate coverage
5. Enable rules once verified