What is beeps?

beeps routes alerts from your monitoring systems to on-call engineers and AI agents. When an incident occurs, beeps can notify humans and kick off automated triage at the same time — or sequentially, however you want to set it up.

The Flow: How Alerts Move Through the System

Here’s what happens when an incident occurs:

Monitoring System (Sentry, Datadog, etc.)
    ↓
    Sends webhook to beeps
    ↓
Alert Created
    ↓
Relay (routing pipeline)
    ↓
Relay Rules (ordered actions)
    ├─ [Group: agents] → AI Agent starts working
    │                     (uses Integration credentials)
    │
    └─ [Group: humans] → Find on-call user (from Schedule)
                          → Send notification (via Contact Methods)

Core concepts

Relays

Relays are alert routing pipelines. When an alert arrives, the relay runs it through an ordered set of rules. Think of a relay as “what should happen when this alert fires.” You’ll typically have one per service or environment (“Production Alerts”, “Staging Alerts”).

Set externalKey on relays so your config scripts are idempotent.

Relay rules

Rules are the individual actions inside a relay. Three types:

• schedule_notify — notify the on-call user from a schedule
• webhook — POST to an external URL (Slack, PagerDuty, etc.)
• agent — invoke an AI agent (Devin, Cursor)

Rules have a group and an order. Same group = sequential (order 1 runs, then 2, then 3). Different groups = parallel. This is how you control whether agents and humans get notified at the same time or one after the other:

// Parallel — different groups, both fire immediately
Rule 1: { group: "agents", order: 1, ruleType: "agent" }
Rule 2: { group: "humans", order: 1, ruleType: "schedule_notify" }

// Sequential — same group, agent tries first
Rule 1: { group: "default", order: 1, ruleType: "agent" }
Rule 2: { group: "default", order: 2, ruleType: "schedule_notify" }

Schedules

Schedules define on-call rotations — who is on-call and when it rotates. You pick daily or weekly, set a startDay and startTime (UTC), and add members. Members rotate in the order they were added.

Contact methods

Each user needs at least one contact method (email or SMS) to receive notifications. We recommend both. Phone numbers should be in E.164 format (+14155551234).

Integrations

Integrations store API credentials for AI agents (Devin, Cursor). The keys are encrypted and never returned in API responses. Don’t confuse these with observability integrations — agent integrations tell beeps how to talk to agents, while observability integrations are webhooks that monitoring tools use to send alerts into beeps.

Webhooks

Each relay gets a webhook URL (https://hooks.beeps.dev/{webhookKey}) that monitoring systems POST to. When a request comes in, beeps detects the provider, normalizes the payload, creates an alert, and kicks off the relay.

Alerts

Alerts are incidents created from webhook payloads — things like “High CPU usage on web-01” with a severity of critical. They carry a title, severity (critical/high/medium/low/info), optional message, and arbitrary metadata JSON for context like server names or error rates.

Alert Lifecycle

1. Created - Alert arrives via webhook
2. Responded - Someone (human or AI) is working on it
3. Assigned - Explicitly assigned to a specific user
4. Resolved - Issue is fixed

Responding to an alert cancels any pending relay executions, preventing duplicate notifications.

Typical Setup Order

When configuring beeps for the first time, follow this order:

1. Create a Relay - The routing pipeline
2. Create a Schedule - Define on-call rotation
3. Add Schedule Members - Add team members to rotation
4. Add Contact Methods - Configure email/SMS for users
5. Create Integration (optional) - Set up AI agent credentials
6. Create Relay Rules - Define what happens when alerts arrive
7. Test - Send a test alert to verify everything works

Ready to get started? Follow the Quickstart to set up relays, schedules, notifications, and AI agents.

Next Steps

• Quickstart - Set up humans and AI agents
• Best Practices - Configuration guidelines
• Relays - Alert routing in depth
• Schedules - On-call rotations

Questions?

Q: What’s the difference between Agent Integrations and Observability Integrations?

A: Agent Integrations store credentials for AI agents (Devin, Cursor Cloud Agent) so beeps can invoke them. Observability Integrations are webhooks that monitoring systems (Sentry, Datadog) use to send alerts into beeps.

Q: Can I have multiple relays?

A: Yes. You might have separate relays for production vs staging, or different relays for different services.

Q: What happens if no one is on-call?

A: The schedule_notify rule won’t send notifications. Make sure your schedule always has at least one member.

Q: Can I test without sending real alerts?

A: Yes — just POST a test payload to your webhook URL, or use the SDK to create test alerts programmatically.