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

# Incoming API

> Send alerts to Warrn from any tool that can hit a URL.

If something in your stack can detect a problem and send an HTTP request, it can create alerts in Warrn. Add the **Incoming API** integration on a team or service, copy the URL it gives you, and POST your alerts to it.

This is the right choice when:

* You want a simple URL to give to a script, a monitoring tool, or a homegrown system.
* You don't want to manage API keys or set request headers.
* The alerts should always land on the same team (or same service).

If you instead want one API key that can create alerts on different teams from one place, use the [Alerts REST API](/api-reference/alerts/create).

## Set it up

<Steps>
  <Step title="Add the integration">
    Open the team or service you want alerts to land on, go to the **Integrations** tab, and add **Incoming API**.

    * Added on a **service** → alerts go to that service (and are routed to the service's team).
    * Added on a **team** → alerts go straight to the team.

    Warrn will show you a URL that looks like:

    ```
    https://api.warrn.io/integrations/webhook/<your-key>
    ```

    Copy it. Anyone with this URL can create alerts on this team or service, so treat it like a password.
  </Step>

  <Step title="Create your first alert">
    Send a POST to the URL with a JSON body. The only thing you need is a `name`.

    ```bash theme={null}
    curl -X POST "https://api.warrn.io/integrations/webhook/<your-key>" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "High CPU on web-01",
        "description": "CPU has been above 90% for 5 minutes.",
        "severity": "high",
        "alert_alias": "cpu-high-prod-web-01",
        "tags": ["infrastructure", "cpu"],
        "metadata": {"host": "web-01", "region": "us-east-1"}
      }'
    ```

    You'll see the alert appear in Warrn within a second.

    **What you can send:**

    | Field             | What it's for                                                                                               |
    | ----------------- | ----------------------------------------------------------------------------------------------------------- |
    | `name` (required) | The headline you'll see in the alert list                                                                   |
    | `description`     | More detail, shown on the alert page                                                                        |
    | `severity`        | `critical`, `high`, `medium`, or `low`. Defaults to `medium` if you don't set it.                           |
    | `alert_alias`     | A stable name *you* choose for this alert (e.g. `cpu-high-prod-web-01`). See "Stop duplicate alerts" below. |
    | `tags`            | A list of strings for filtering and search                                                                  |
    | `metadata`        | Any extra JSON you want to keep with the alert (host names, links to graphs, runbook URLs)                  |
  </Step>

  <Step title="Tell Warrn when the problem is fixed">
    When the issue clears on your side, POST to the same URL with `status: "resolved"` and the alias you used when you created the alert:

    ```bash theme={null}
    curl -X POST "https://api.warrn.io/integrations/webhook/<your-key>" \
      -H "Content-Type: application/json" \
      -d '{"status": "resolved", "alert_alias": "cpu-high-prod-web-01"}'
    ```

    Warrn finds the matching open alert and closes it. If there's nothing open with that alias (already resolved, or never fired), you'll still get a `200 OK` so you can safely retry without worrying about duplicate close events.
  </Step>
</Steps>

## Stop duplicate alerts with `alert_alias`

If your system fires the same alert every minute until the problem is fixed, you don't want Warrn to create a new alert every minute. That's what `alert_alias` is for.

Pick a name that's unique to the *thing being alerted on*, not unique per fire. Good examples:

* `cpu-high-prod-web-01`
* `disk-full-db-primary`
* `payments-error-rate-checkout-service`

Send the same alias every time the alert fires. While the first alert is still open or acknowledged, Warrn updates its counter instead of creating a new one. After someone resolves it (or you send the resolve webhook), the next fire creates a fresh alert.

This is also what lets you close the alert without ever having to remember its Warrn ID - you just send the alias back when the problem is fixed.

## What this integration *doesn't* do

* **No acknowledge over webhook.** You can create alerts and resolve them via this URL, but acknowledging happens in the Warrn UI or via the [REST API](/api-reference/alerts/acknowledge).
* **One destination per URL.** Each URL is tied to one team or service. If you want one credential that can create alerts on any team, the [REST API](/api-reference/alerts/create) is the better fit.

## Incoming API vs REST API

|                      | Incoming API (this page)                                                     | [REST API](/api-reference/alerts/create)                                |
| -------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| How you authenticate | Key is part of the URL                                                       | Bearer token in a header                                                |
| Where alerts go      | Always the team or service you set up the URL on                             | You pick a team per alert                                               |
| What's in the body   | Just `name`, everything else optional                                        | `name`, `description`, `severity`, `team_id`                            |
| What you can do      | Create alerts, resolve by alias                                              | Create, acknowledge, resolve, list, search                              |
| Best for             | Giving a URL to a tool or script that just needs to fire alerts at one place | Custom scripts, CI jobs, anything managing alerts across multiple teams |