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

# Generic webhook payload

> The full contract for the JSON accepted by Generic alert sources.

## Request

```bash theme={null}
POST https://ingress.aciona.me/webhooks/<alertSourceId>
Content-Type: application/json
X-Aciona-Token: <sourceToken>
```

The body is a **JSON object** representing a single alert.

## Fields

<ParamField body="title" type="string">
  Incident title. When absent, aciona.me uses `Untitled alert`.
</ParamField>

<ParamField body="description" type="string">
  Detail of the problem. Shown in the incident body and in notifications.
</ParamField>

<ParamField body="severity" default="warning" type="string">
  Alert severity. Accepts the canonical values `critical`, `high`, `warning` and `info`, plus common synonyms (`p1`, `sev2`, `error`, `warn`, `low`…). Unrecognized values fall back to `warning`.
</ParamField>

<ParamField body="service" type="string">
  Name of the affected service as registered in aciona.me. Also accepted as `labels.service`. Determines the responsible team and therefore who gets paged.
</ParamField>

<ParamField body="externalId" type="string">
  Stable identifier of the problem at the source. This is the correlation key used to aggregate repeated triggers into the same incident.
</ParamField>

<ParamField body="status" default="firing" type="string">
  Accepts `firing` or `alerting`. Any other value makes the alert accepted and **discarded**, with no incident created. When absent, it is treated as `firing`.
</ParamField>

<ParamField body="labels" type="object">
  Free-form labels, preserved on the incident. Useful for context (`env`, `region`, `cluster`, `job`).
</ParamField>

<ParamField body="url" type="string">
  Link back to the alert's origin. Also accepted as `externalUrl`.
</ParamField>

## Full example

```json theme={null}
{
  "externalId": "checkout-error-rate",
  "title": "Checkout error rate above 5%",
  "description": "5xx errors on 7.2% of requests over the last 5 minutes",
  "severity": "critical",
  "service": "checkout",
  "status": "firing",
  "labels": {
    "env": "prod",
    "region": "sa-east-1",
    "cluster": "prod-a"
  },
  "url": "https://observability.example.com/d/checkout"
}
```

## Minimal example

```json theme={null}
{
  "title": "Nightly job failed",
  "service": "data-pipeline"
}
```

## Response

```json theme={null}
{ "status": "accepted" }
```

With `HTTP 202`. Processing is asynchronous: the incident shows up in the dashboard within seconds.

## Limitations

<Warning>
  `Generic` sources **do not support auto-resolution**. Sending `"status": "resolved"` discards the alert; it does not resolve the incident. For auto-resolution, use your tool's dedicated source type.
</Warning>

* One POST represents one alert. For multiple alerts, send multiple POSTs.
* The body has a size limit (1 MB by default).

<Card title="Generic webhook guide" icon="code" horizontal href="/en/integrations/generic-webhook" />