Generic webhook payload

Request

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

string

Incident title. When absent, aciona.me uses Untitled alert.

string

Detail of the problem. Shown in the incident body and in notifications.

string

default:"warning"

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.

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.

string

Stable identifier of the problem at the source. This is the correlation key used to aggregate repeated triggers into the same incident and to match a recovery with the open incident. Required when status is resolved: it must be non-empty text (not whitespace only) or a number; otherwise the request is rejected with 400. It is compared exactly as sent.

string

default:"firing"

firing or alerting open or aggregate; resolved resolves the incident opened by this source with the same externalId. The comparison is case-insensitive. Any other value (including ok, normal, recovered, closed) makes the alert accepted and discarded, with no incident created or resolved. When absent, it is treated as firing.

object

Free-form labels, preserved on the incident. Useful for context (env, region, cluster, job).

string

Link back to the alert’s origin. Also accepted as externalUrl.

Full example

{
  "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

{
  "title": "Nightly job failed",
  "service": "data-pipeline"
}

Recovery example

{
  "status": "resolved",
  "externalId": "checkout-error-rate"
}

Resolves the incident opened by this source with the same externalId, from any active state — including acknowledged or taken over — and closes it automatically 5 minutes later. Title and description may be included and are not used for correlation. Details in Automatic recovery.

Response

{ "accepted": true, "alertIds": ["<uuid>"] }

With HTTP 202. Processing is asynchronous: the incident shows up (or is resolved) in the dashboard within seconds. When the status is ignored, alertIds is empty. The 202 confirms acceptance, not that an incident was created or resolved.

Limitations

One POST represents one alert. For multiple alerts, send multiple POSTs.
The body has a size limit (1 MB by default).
A recovery only resolves incidents opened by the same source; it never uses the title, the service or the content signature.
Reusing the same key across outages lets a late recovery resolve the next occurrence. If that matters, use one key per episode.
Under bursts, a recovery may be processed before its opening and then resolves nothing.

Reference

Generic webhook payload

Request

Fields

Full example

Minimal example

Recovery example

Response

Limitations

Generic webhook guide

​Request

​Fields

​Full example

​Minimal example

​Recovery example

​Response

​Limitations

Generic webhook guide

Request

Fields

Full example

Minimal example

Recovery example

Response

Limitations