Core Concepts¶

Understanding the core concepts of Relaye will help you make the most of its features and streamline your notification workflow.

How Relaye Works¶

Relaye connects your existing services to your notification channels, giving you control over how alerts and messages are routed:

flowchart LR
    ES[Your Services] -->|Send Data| I[Inputs]
    I -->|Transform| C[Connections]
    C -->|Deliver| O[Outputs]
    O -->|Notify| ENS[Your Notification Channels]

    style ES fill:#d4ebf2,stroke:#333,stroke-width:1px
    style ENS fill:#d4ebf2,stroke:#333,stroke-width:1px

Let's explore each component and how they work together:

Inputs¶

Inputs are entry points that receive information from your external services and systems.

Key Features¶

• Each input has a unique URL or email address that you can configure in your systems
• You can create multiple inputs for different services or purposes
• Inputs can route notifications to multiple destinations
• Inputs securely receive and process incoming data

classDiagram
    class Input {
        Receive data from external services
        Each has a unique endpoint
        Can connect to multiple outputs
    }

    class InputTypes {
        Generic Webhook
        Email
        Grafana Alert
        Stripe
    }

    Input -- InputTypes

Available Input Types¶

• Generic Webhook: A versatile HTTP endpoint that accepts JSON payloads from any system that can send webhooks
• Email: A dedicated email address that forwards received messages to your notification channels
• Grafana Alert: Specifically formatted to receive and process Grafana monitoring alerts
• Stripe: Designed to receive payment and subscription events from Stripe

Outputs¶

Outputs are the destination channels where Relaye sends your notifications.

Key Features¶

• Simple configuration for popular notification platforms
• Secure credential management
• Flexible formatting options for each platform
• Support for multiple teams and projects

classDiagram
    class Output {
        Send notifications to your channels
        Each requires simple configuration
        Can receive from multiple inputs
    }

    class OutputTypes {
        Telegram
        Slack
        Discord
        Email (AWS SES)
        Generic Webhook
    }

    Output -- OutputTypes

Available Output Types¶

• Telegram: Send messages to Telegram chats, groups, or channels
• Slack: Post notifications to Slack channels
• Discord: Send messages to Discord channels
• Email (AWS SES): Send emails via Amazon SES
• Generic Webhook: Forward notifications to another HTTP endpoint

Connections¶

Connections link your inputs to your outputs, defining how information flows and is transformed.

Key Features¶

• Custom message templates for each connection
• Easy enable/disable controls
• Support for data transformation
• Multiple connections can exist between different inputs and outputs

flowchart LR
    I1[Server Alert Input] --> C1[Connection 1]
    I1 --> C2[Connection 2]
    C1 -->|"Template: 🚨 Alert: {{alert_name}}"| O1[Telegram Channel]
    C2 -->|"Template: [ALERT] {{alert_name}} on {{server}}"| O2[Slack #alerts]

    style C1 fill:#f9d6d2,stroke:#333
    style C2 fill:#d2e5f9,stroke:#333

Templating¶

Connections use templates to transform the raw data into formatted messages for each platform:

• Simple variable substitution with {{ variable_name }}
• Conditional formatting with {% if condition %}...{% endif %}
• Support for markdown formatting in platforms that allow it
• Access to all data fields from the input payload

How Templating Works with Payloads¶

When an input receives data (like a webhook or email), Relaye processes that data and makes all fields available as variables in your templates. Here's how it works:

1. Incoming Data: Your service sends a JSON payload to Relaye's input
2. Data Parsing: Relaye automatically parses the payload structure
3. Variable Availability: All fields become available as variables in your template
4. Template Processing: Your template uses these variables to create a formatted message

For example, if you receive this webhook payload:

{
  "alert": {
    "name": "High CPU Usage",
    "severity": "critical",
    "server": "app-server-01",
    "value": 95.2,
    "threshold": 90
  },
  "timestamp": "2025-04-22T14:30:00Z"
}

You can reference any of these fields in your template:

🚨 {{ alert.severity | upcase }} ALERT: {{ alert.name }}
Server: {{ alert.server }}
Value: {{ alert.value }}% (Threshold: {{ alert.threshold }}%)
Time: {{ timestamp | date: "%H:%M" }}

Which might be rendered as:

🚨 CRITICAL ALERT: High CPU Usage
Server: app-server-01
Value: 95.2% (Threshold: 90%)
Time: 14:30

This templating system gives you complete control over how your notifications appear in different channels, allowing you to highlight important information and format it appropriately for each platform.

Teams¶

Teams let you collaborate with colleagues on managing notifications.

Key Features¶

• Share access to inputs and outputs with team members
• Team-based permissions and management
• Support for multiple teams with different purposes

flowchart TB
    Team1[Team: Engineering] --- U1[Team Member: Alice]
    Team1 --- U2[Team Member: Bob]
    Team1 --- I1[Input: Monitoring Alerts]
    Team1 --- O1[Output: Eng Slack Channel]

    Team2[Team: Customer Support] --- U3[Team Member: Carol]
    Team2 --- U2
    Team2 --- I2[Input: Customer Tickets]
    Team2 --- O2[Output: Support Telegram Group]

    classDef team fill:#e1d5e7,stroke:#9673a6
    classDef user fill:#d5e8d4,stroke:#82b366
    classDef input fill:#dae8fc,stroke:#6c8ebf
    classDef output fill:#fff2cc,stroke:#d6b656

    class Team1,Team2 team
    class U1,U2,U3 user
    class I1,I2 input
    class O1,O2 output

How Notifications Flow¶

When a notification is triggered, here's what happens:

sequenceDiagram
    participant ES as Your Service
    participant I as Relaye Input
    participant C as Connection
    participant O as Relaye Output
    participant D as Your Notification Channel

    ES->>I: Send webhook/email
    I->>C: Process using template
    C->>O: Format for destination
    O->>D: Deliver notification
    Note over I,O: All steps are logged for visibility

1. Receive: Your service sends a webhook or email to your Relaye input
2. Process: Relaye identifies all connections that use this input
3. Transform: For each connection, the template is applied to format the data
4. Deliver: The formatted notification is sent to each configured output
5. Log: The entire process is logged for visibility and troubleshooting

Activity Logs¶

Relaye maintains detailed logs of all incoming data and outgoing notifications:

graph TD
    Log[Activity Logs]
    IL[Incoming Events]
    OL[Outgoing Notifications]

    Log --> IL
    Log --> OL

    IL --> IL1[GitHub: Push to main]
    IL --> IL2[Grafana: CPU Alert]
    IL --> IL3[Stripe: Payment]

    OL --> OL1[Telegram: Success]
    OL --> OL2[Slack: Success]
    OL --> OL3[Email: Failed]

    style OL1 fill:#d5e8d4,stroke:#82b366
    style OL2 fill:#d5e8d4,stroke:#82b366
    style OL3 fill:#f8cecc,stroke:#b85450
    style IL1 fill:#dae8fc,stroke:#6c8ebf
    style IL2 fill:#dae8fc,stroke:#6c8ebf
    style IL3 fill:#dae8fc,stroke:#6c8ebf

• Incoming Events: Record of all received webhooks and emails
• Outgoing Notifications: Record of all notification attempts and their status

These logs provide visibility into your notification pipeline and help with troubleshooting if issues arise.

Getting Started¶

Now that you understand Relaye's core concepts, you're ready to:

1. Create your first input to receive webhooks or emails
2. Set up outputs for your favorite notification channels
3. Create connections to link them together with custom templates
4. Invite team members to collaborate

Check out our quickstart guide for step-by-step instructions on setting up your first notification pipeline.