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

# Alerts & Webhooks

> Get real-time notifications about gateway events via email and webhook integrations.

MetrixLLM can trigger notifications when important events occur in your workspace. You can receive alerts via **email** and **webhooks** (Slack, Discord, or custom HTTP endpoints). This allows you to integrate gateway observability directly into your own backend or alerting systems.

## Webhook events

The gateway fires the following events:

| Event              | Trigger condition                                                                |
| :----------------- | :------------------------------------------------------------------------------- |
| `request.complete` | A request was successfully processed and returned to the client.                 |
| `request.failed`   | A request failed completely (all routing attempts and fallbacks were exhausted). |
| `rate_limit.hit`   | A request was rejected because a workspace or route rate limit was reached.      |
| `budget.threshold` | The workspace spend has crossed a configured budget threshold.                   |

## Webhook notifications

Each alert rule can send notifications to one or more webhook URLs in addition to (or instead of) email recipients. The dashboard accepts arbitrary webhook URLs, so you can connect any HTTP endpoint that can receive POST requests.

### Supported webhook types

| Type        | URL pattern                            | Notes                                                                                  |
| :---------- | :------------------------------------- | :------------------------------------------------------------------------------------- |
| **Slack**   | `https://hooks.slack.com/...`          | Posts a formatted message to a Slack channel via Incoming Webhooks.                    |
| **Discord** | `https://discord.com/api/webhooks/...` | Posts a formatted message to a Discord channel via webhook.                            |
| **Custom**  | Any HTTP/HTTPS URL                     | Receives a JSON payload. Your endpoint must handle the POST and return a 2xx response. |

## Configuring webhooks

<Steps>
  <Step title="Open Settings">
    In your workspace, go to **Settings → Alerts**.
  </Step>

  <Step title="Create or edit a rule">
    Click **New Rule** or edit an existing rule.
  </Step>

  <Step title="Add webhook URLs">
    In the **Webhooks** field, paste a Slack, Discord, or custom endpoint URL and press **Enter** to add it. You can add multiple URLs.
  </Step>

  <Step title="Select events">
    Choose which of the 4 events you want this rule to trigger on.
  </Step>

  <Step title="Set a secret (Optional)">
    Enter a cryptographically secure secret. The gateway will use this to sign the payload so your server can verify the request came from MetrixLLM.
  </Step>
</Steps>

<Note>
  An alert rule requires at least one notification destination — either one or more team member emails, one or more webhook URLs, or both.
</Note>

## Getting a Slack webhook URL

1. Open your Slack workspace and go to **Apps → Incoming Webhooks** (or visit `https://api.slack.com/apps`).
2. Create a new webhook (or use an existing one) and select the channel you want alerts posted to.
3. Copy the webhook URL (it starts with `https://hooks.slack.com/services/...`) and paste it into the alert rule's **Webhooks** field.

## Getting a Discord webhook URL

1. Open your Discord server and go to **Server Settings → Integrations → Webhooks**.
2. Click **New Webhook**, name it, select the channel, and click **Copy Webhook URL**.
3. Paste the URL (it starts with `https://discord.com/api/webhooks/...`) into the alert rule's **Webhooks** field.

## Custom endpoint payload

When an alert fires, each configured webhook receives a POST request with a JSON body containing the alert details:

```json theme={null}
{
  "event": "budget.threshold",
  "workspace_id": "ws_abc123",
  "rule_name": "High Spend Alert",
  "metric": "cost",
  "condition": "gt",
  "threshold": 100,
  "actual_value": 142.37,
  "window_minutes": 60,
  "message": "Total cost exceeded $100 in a 60 min window.",
  "timestamp": "2026-07-22T14:30:00Z"
}
```

Your endpoint should return a `200 OK` (or any 2xx) response. Non-2xx responses or timeouts will not be retried.

## Payload signature verification

If you configured a secret, every webhook delivery includes an `X-Metrix-Signature` header. This header contains an HMAC-SHA256 signature generated using your secret and the raw JSON payload body.

Here is an example of how to verify the signature in Python:

```python theme={null}
import hmac
import hashlib

def verify_signature(payload_bytes: bytes, secret: str, signature_header: str) -> bool:
    expected_sig = "sha256=" + hmac.HMAC(
        secret.encode("utf-8"), 
        payload_bytes, 
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(expected_sig, signature_header)
```

<Warning>
  Webhook deliveries are **fire-and-forget**. The gateway sends the payload asynchronously. If your endpoint is down or returns a 5xx error, the delivery will not be automatically retried.
</Warning>