> ## Documentation Index
> Fetch the complete documentation index at: https://docs.easyalert.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Settings

> Configure notification channels and webhook integrations

## Overview

The Settings page allows you to configure notification channels for sending alerts to external systems. You can set up webhooks to integrate with tools like Slack, Microsoft Teams, or any custom HTTP endpoint.

<CardGroup cols={2}>
  <Card title="Webhook Channels" icon="webhook">
    Send notifications to Slack, Teams, or custom endpoints
  </Card>

  <Card title="Custom Payloads" icon="code">
    Define custom JSON templates with dynamic variables
  </Card>

  <Card title="Authentication" icon="lock">
    Support for Bearer tokens, API keys, and Basic Auth
  </Card>

  <Card title="Test & Validate" icon="vial">
    Test channels before using them in production
  </Card>
</CardGroup>

***

## Webhook Channels

Webhook channels allow you to send HTTP requests to external systems when incidents occur. Each channel can be configured with its own URL, authentication, and payload template.

### Channel List View

The Settings page displays all configured webhook channels as cards:

| Element           | Description                             |
| ----------------- | --------------------------------------- |
| **Name**          | Channel identifier                      |
| **Description**   | Purpose of the channel                  |
| **URL**           | Target webhook endpoint                 |
| **Method**        | HTTP method (GET, POST, PUT, PATCH)     |
| **Status**        | Active or Inactive toggle               |
| **Default Badge** | Indicates default channel for this type |

<Tip>
  Inactive channels appear with reduced opacity. You can toggle status without
  deleting the channel.
</Tip>

***

## Creating a Webhook Channel

<Steps>
  <Step title="Open Create Dialog">
    Click the **Add Webhook** button in the page header
  </Step>

  <Step title="Enter Basic Info">
    * **Name** — Descriptive channel name (required) - **Description** — Explain
      what this channel does
  </Step>

  <Step title="Configure Webhook URL">
    Enter the target URL for the webhook (e.g., Slack incoming webhook URL)
  </Step>

  <Step title="Select HTTP Method">
    Choose the HTTP method: - **POST** — Most common for webhooks - **PUT** —
    For update operations - **PATCH** — For partial updates - **GET** — For
    simple notifications
  </Step>

  <Step title="Configure Authentication">
    Select authentication type and provide credentials if needed
  </Step>

  <Step title="Set Timeout">
    Configure request timeout in seconds (default: 30)
  </Step>

  <Step title="Create Payload Template">
    Define the JSON payload with template variables
  </Step>

  <Step title="Save Channel">Click **Create** to save the channel</Step>
</Steps>

***

## Authentication Types

Configure how EasyAlert authenticates with your webhook endpoint.

<Tabs>
  <Tab title="None">
    No authentication required. Use for public webhooks like Slack incoming webhooks.

    ```
    Authentication: None
    ```
  </Tab>

  <Tab title="Bearer Token">
    Send a Bearer token in the Authorization header.

    | Field          | Value                                       |
    | -------------- | ------------------------------------------- |
    | Authentication | Bearer Token                                |
    | Token          | `<YOUR_BEARER_TOKEN>`                       |
    | Header sent    | `Authorization: Bearer <YOUR_BEARER_TOKEN>` |
  </Tab>

  <Tab title="API Key">
    Send an API key in a custom header.

    | Field          | Value                       |
    | -------------- | --------------------------- |
    | Authentication | API Key                     |
    | API Key        | `<YOUR_API_KEY>`            |
    | Header sent    | `X-API-Key: <YOUR_API_KEY>` |
  </Tab>

  <Tab title="Basic Auth">
    Send username and password as Base64-encoded Basic authentication.

    | Field          | Value                                   |
    | -------------- | --------------------------------------- |
    | Authentication | Basic Auth                              |
    | Credentials    | `username:password` (Base64 encoded)    |
    | Header sent    | `Authorization: Basic <BASE64_ENCODED>` |
  </Tab>
</Tabs>

<Warning>
  Authentication credentials are stored securely but are never displayed after
  saving. You'll need to re-enter them when editing.
</Warning>

***

## Payload Templates

Payload templates define the JSON body sent to your webhook. Use template variables to include dynamic incident data.

### Template Editor Features

* **Syntax highlighting** for JSON
* **Real-time validation** shows errors immediately
* **Format button** to auto-format valid JSON
* **Copy button** to copy template to clipboard
* **Variable reference** panel with all available placeholders

### Available Variables

<Tabs>
  <Tab title="Incident Variables">
    | Variable                        | Description                                   |
    | ------------------------------- | --------------------------------------------- |
    | `{{incident.id}}`               | Unique incident identifier                    |
    | `{{incident.incidentNumber}}`   | Human-readable incident number                |
    | `{{incident.title}}`            | Incident title                                |
    | `{{incident.description}}`      | Incident description                          |
    | `{{incident.status}}`           | Current status (open, acknowledged, resolved) |
    | `{{incident.severity}}`         | Severity level                                |
    | `{{incident.priority}}`         | Priority (P1-P5)                              |
    | `{{incident.host}}`             | Affected hostname                             |
    | `{{incident.hostIp}}`           | Host IP address                               |
    | `{{incident.service}}`          | Service name                                  |
    | `{{incident.environment}}`      | Environment (production, staging, etc.)       |
    | `{{incident.region}}`           | Geographic region                             |
    | `{{incident.sourceType}}`       | Integration source type                       |
    | `{{incident.triggeredAt}}`      | When the incident was triggered               |
    | `{{incident.acknowledgedAt}}`   | When acknowledged (if applicable)             |
    | `{{incident.currentLevel}}`     | Current escalation level                      |
    | `{{incident.alertCount}}`       | Number of alerts in incident                  |
    | `{{incident.tags}}`             | All tags as object                            |
    | `{{incident.tags.customer}}`    | Specific tag value                            |
    | `{{incident.tags.environment}}` | Environment tag                               |
    | `{{incident.tags.team}}`        | Team tag                                      |
  </Tab>

  <Tab title="Target Variables">
    | Variable              | Description                                 |
    | --------------------- | ------------------------------------------- |
    | `{{target.id}}`       | Target user/contact ID                      |
    | `{{target.name}}`     | Target name                                 |
    | `{{target.type}}`     | Target type (user, contact, schedule, team) |
    | `{{target.phone}}`    | Phone number                                |
    | `{{target.email}}`    | Email address                               |
    | `{{target.role}}`     | User role                                   |
    | `{{target.language}}` | Language preference                         |
    | `{{target.timezone}}` | Timezone                                    |
  </Tab>

  <Tab title="Other Variables">
    | Variable                  | Description              |
    | ------------------------- | ------------------------ |
    | `{{tenant.id}}`           | Tenant identifier        |
    | `{{tenant.slug}}`         | Tenant slug              |
    | `{{tenant.timezone}}`     | Tenant timezone          |
    | `{{escalation.level}}`    | Current escalation level |
    | `{{escalation.policyId}}` | Escalation policy ID     |
    | `{{message}}`             | Custom message text      |
  </Tab>

  <Tab title="Filters">
    Apply transformations to variables:

    | Filter     | Usage                                     | Result                  |
    | ---------- | ----------------------------------------- | ----------------------- |
    | `upper`    | `{{incident.severity\|upper}}`            | CRITICAL                |
    | `default`  | `{{incident.host\|default("unknown")}}`   | Fallback value if empty |
    | `truncate` | `{{incident.description\|truncate(100)}}` | Truncate to length      |
  </Tab>
</Tabs>

***

## Pre-built Templates

Use these templates as starting points for common integrations.

<AccordionGroup>
  <Accordion title="Slack Template">
    ```json theme={null}
    {
      "attachments": [
        {
          "color": "{{incident.severity == 'critical' ? '#FF0000' : '#FFA500'}}",
          "title": "{{incident.title}}",
          "title_link": "https://admin.easyalert.io/incidents/{{incident.id}}",
          "text": "{{incident.description}}",
          "fields": [
            {
              "title": "Severity",
              "value": "{{incident.severity}}",
              "short": true
            },
            {
              "title": "Host",
              "value": "{{incident.host}}",
              "short": true
            },
            {
              "title": "Service",
              "value": "{{incident.service}}",
              "short": true
            },
            {
              "title": "Environment",
              "value": "{{incident.environment}}",
              "short": true
            },
            {
              "title": "Assignee",
              "value": "{{target.name}}",
              "short": true
            },
            {
              "title": "Customer",
              "value": "{{incident.tags.customer}}",
              "short": true
            }
          ],
          "footer": "EasyAlert",
          "ts": "{{incident.triggeredAt}}"
        }
      ]
    }
    ```

    <Info>
      For Slack, use the incoming webhook URL from your Slack app. No authentication is needed as the token is embedded in the URL.
    </Info>
  </Accordion>

  <Accordion title="Microsoft Teams Template">
    ```json theme={null}
    {
      "@type": "MessageCard",
      "@context": "http://schema.org/extensions",
      "themeColor": "{{incident.severity == 'critical' ? 'FF0000' : 'FFA500'}}",
      "summary": "{{incident.title}}",
      "sections": [
        {
          "activityTitle": "{{incident.title}}",
          "facts": [
            {
              "name": "Severity",
              "value": "{{incident.severity}}"
            },
            {
              "name": "Host",
              "value": "{{incident.host}}"
            },
            {
              "name": "Service",
              "value": "{{incident.service}}"
            },
            {
              "name": "Environment",
              "value": "{{incident.environment}}"
            },
            {
              "name": "Status",
              "value": "{{incident.status}}"
            }
          ],
          "text": "{{incident.description}}"
        }
      ],
      "potentialAction": [
        {
          "@type": "OpenUri",
          "name": "View Incident",
          "targets": [
            {
              "os": "default",
              "uri": "https://admin.easyalert.io/incidents/{{incident.id}}"
            }
          ]
        }
      ]
    }
    ```

    <Info>
      For Teams, use the incoming webhook URL from your Teams channel connector.
    </Info>
  </Accordion>

  <Accordion title="Generic Webhook Template">
    ```json theme={null}
    {
      "event": "incident.triggered",
      "incident": {
        "id": "{{incident.id}}",
        "number": "{{incident.incidentNumber}}",
        "title": "{{incident.title}}",
        "description": "{{incident.description}}",
        "severity": "{{incident.severity}}",
        "priority": "{{incident.priority}}",
        "status": "{{incident.status}}",
        "host": "{{incident.host}}",
        "service": "{{incident.service}}",
        "environment": "{{incident.environment}}",
        "triggeredAt": "{{incident.triggeredAt}}",
        "url": "https://admin.easyalert.io/incidents/{{incident.id}}"
      },
      "assignee": {
        "name": "{{target.name}}",
        "email": "{{target.email}}"
      },
      "tags": "{{incident.tags}}"
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Testing Channels

Before using a channel in production, test it to verify the configuration is correct.

### How to Test

1. Click the **three-dot menu** (⋮) on a channel card
2. Select **Test**
3. In the test dialog, click **Send Test**
4. Review the results

### Test Results

| Field             | Description                           |
| ----------------- | ------------------------------------- |
| **Status**        | Success (green) or Failed (red)       |
| **Message**       | Response message or error description |
| **Response Code** | HTTP status code (200, 201, etc.)     |
| **Duration**      | Request time in milliseconds          |

<Tip>
  A successful test means the webhook endpoint is reachable and accepted the
  request. Check your target system to verify the message was received
  correctly.
</Tip>

***

## Default Channel

You can mark one webhook channel as the **default** for each channel type. The default channel is used when:

* No specific channel is configured in escalation policy levels
* Webhooks are selected but no specific channel is specified

### Setting Default Channel

1. Open the channel edit dialog
2. Toggle **Set as Default** to on
3. Save changes

<Info>
  Only one channel per type can be the default. Setting a new default
  automatically removes the default status from the previous channel.
</Info>

***

## Managing Channels

### Editing Channels

1. Click the **three-dot menu** (⋮) on a channel
2. Select **Edit**
3. Modify settings as needed
4. Click **Update** to save

### Toggling Active Status

Use the switch on each channel card to quickly enable or disable:

* **Active** — Channel is used for notifications
* **Inactive** — Channel is skipped (useful for maintenance or testing)

<Tip>
  Inactive channels remain configured but don't receive notifications. Use this
  instead of deleting when you might need the channel again.
</Tip>

### Deleting Channels

1. Click the three-dot menu
2. Select **Delete**
3. Confirm deletion

<Warning>
  Deleted channels cannot be recovered. Any escalation policy levels using this
  channel will need to be reconfigured.
</Warning>

***

## Common Integrations

<AccordionGroup>
  <Accordion title="Slack">
    **Setup:**

    1. Create an Incoming Webhook in Slack App settings
    2. Copy the webhook URL
    3. Create channel with URL and Slack template
    4. No authentication needed (token in URL)

    **URL Format:** Slack incoming webhook URL from your app settings
  </Accordion>

  <Accordion title="Microsoft Teams">
    **Setup:**

    1. Add Incoming Webhook connector to your Teams channel
    2. Copy the webhook URL
    3. Create channel with URL and Teams template
    4. No authentication needed (token in URL)

    **URL Format:** Teams incoming webhook URL from your channel connector
  </Accordion>

  <Accordion title="Discord">
    **Setup:**

    1. Create a Webhook in Discord channel settings
    2. Copy the webhook URL
    3. Create channel with URL
    4. Use Discord-compatible JSON payload

    **Template:**

    ```json theme={null}
    {
      "content": "**{{incident.title}}**\n{{incident.description}}",
      "embeds": [
        {
          "title": "Incident Details",
          "color": 16711680,
          "fields": [
            {"name": "Severity", "value": "{{incident.severity}}", "inline": true},
            {"name": "Host", "value": "{{incident.host}}", "inline": true}
          ]
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Custom API">
    **Setup:**

    1. Determine your API endpoint URL
    2. Configure authentication (Bearer, API Key, or Basic)
    3. Create payload template matching your API schema
    4. Set appropriate timeout

    **Example with Bearer Auth:**

    | Setting | Value                                     |
    | ------- | ----------------------------------------- |
    | URL     | `https://api.example.com/webhooks/alerts` |
    | Method  | POST                                      |
    | Auth    | Bearer Token                              |
    | Token   | `<YOUR_API_TOKEN>`                        |
  </Accordion>
</AccordionGroup>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Use Descriptive Names">
    Name channels clearly to indicate their purpose: "Slack - Engineering Alerts", "Teams - On-Call Channel", "CRM - Customer Incidents"
  </Accordion>

  <Accordion title="Test Before Production">
    Always test new channels and template changes before relying on them for critical alerts.
  </Accordion>

  <Accordion title="Set Appropriate Timeouts">
    Default timeout is 30 seconds. Reduce for time-sensitive notifications or increase for slow endpoints.
  </Accordion>

  <Accordion title="Use Default Wisely">
    Set a reliable, always-available channel as default to ensure notifications are never lost.
  </Accordion>

  <Accordion title="Include Essential Fields">
    Always include incident ID, title, severity, and a link back to EasyAlert in your templates.
  </Accordion>

  <Accordion title="Handle Missing Data">
    Use the `default` filter for optional fields: `{{incident.host|default("Unknown")}}`
  </Accordion>

  <Accordion title="Keep Credentials Secure">
    Rotate API keys and tokens periodically. Use dedicated service accounts for webhook integrations.
  </Accordion>
</AccordionGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Test returns error">
    1. Verify the webhook URL is correct and accessible 2. Check authentication
       credentials 3. Ensure the payload template is valid JSON 4. Try the request
       manually with curl to diagnose 5. Check if the endpoint has IP restrictions
  </Accordion>

  <Accordion title="Notifications not being sent">
    1. Verify channel is **Active** 2. Check that the channel is selected in
       escalation policy levels 3. Ensure the escalation policy is active and
       assigned 4. Review incident logs for delivery errors
  </Accordion>

  <Accordion title="Payload template errors">
    1. Validate JSON syntax in the editor 2. Check variable names match exactly
       (case-sensitive) 3. Ensure filters are applied correctly 4. Test with a
       minimal template first
  </Accordion>

  <Accordion title="Authentication failures">
    1. Verify credentials are entered correctly 2. Check token hasn't expired 3.
       Ensure auth type matches endpoint requirements 4. Verify the endpoint
       expects the header format used
  </Accordion>

  <Accordion title="Timeout errors">
    1. Increase timeout value 2. Check if endpoint is slow or overloaded 3.
       Verify network connectivity 4. Consider using async webhook if available
  </Accordion>

  <Accordion title="Messages not appearing in Slack/Teams">
    1. Verify webhook URL is correct 2. Check channel/team permissions 3. Ensure
       webhook hasn't been revoked 4. Verify payload matches expected format
  </Accordion>
</AccordionGroup>

***

## Quick Reference

### Authentication Types

| Type    | Header Format                   | Use Case                        |
| ------- | ------------------------------- | ------------------------------- |
| None    | (no header)                     | Slack, Teams incoming webhooks  |
| Bearer  | `Authorization: Bearer {token}` | OAuth APIs, modern REST APIs    |
| API Key | `X-API-Key: {key}`              | Simple API authentication       |
| Basic   | `Authorization: Basic {base64}` | Legacy systems, basic auth APIs |

### HTTP Methods

| Method | Use Case                            |
| ------ | ----------------------------------- |
| POST   | Creating new records, most webhooks |
| PUT    | Replacing existing records          |
| PATCH  | Partial updates                     |
| GET    | Simple notifications without body   |

### Common Template Variables

| Variable                | Example Value        |
| ----------------------- | -------------------- |
| `{{incident.id}}`       | `abc123-def456`      |
| `{{incident.title}}`    | `High CPU on web-01` |
| `{{incident.severity}}` | `critical`           |
| `{{incident.host}}`     | `web-server-01`      |
| `{{incident.service}}`  | `api-gateway`        |
| `{{target.name}}`       | `John Doe`           |
| `{{tenant.slug}}`       | `acme-corp`          |