Generic webhook

Overview

The generic webhook accepts simple JSON from any system that can POST — scripts, CI/CD, internal jobs, tools with no dedicated integration.


Source type	`Generic`
Mechanism	JSON `POST`
Correlation	`externalId`
Auto-resolution	`"status": "resolved"` with the same `externalId`

If your tool has a dedicated source type (Grafana, Prometheus, Datadog, CloudWatch, Zabbix, New Relic), prefer it — field mapping and recovery come ready-made. Use the generic webhook for scripts, in-house monitors and tools with no dedicated integration.

1. Create the alert source

Under Alert sources, create a source of type Generic. Copy the URL and the token.

2. Send the alert

curl -X POST "https://ingress.aciona.me/webhooks/<alertSourceId>" \
  -H "Content-Type: application/json" \
  -H "X-Aciona-Token: <sourceToken>" \
  -d '{
    "externalId": "nightly-etl-job",
    "title": "Nightly ETL job failed",
    "description": "Exited with code 1 after 3 retries",
    "severity": "high",
    "service": "data-pipeline",
    "status": "firing",
    "labels": { "env": "prod", "job": "nightly-etl" },
    "url": "https://ci.example.com/builds/4821"
  }'

Expected response: 202 Accepted.

Accepted fields

Field	Type	Required	Description
`title`	string	recommended	Incident title. Without it, becomes `Untitled alert`.
`description`	string	no	Detail of the problem.
`severity`	string	no	`critical`, `high`, `warning`, `info` or a synonym. Default: `warning`.
`service`	string	recommended	Service name in aciona.me. Also accepted as `labels.service`.
`externalId`	string	recommended; required for a recovery	Stable identifier of the problem. It is the correlation key.
`status`	string	no	`firing` or `alerting` open; `resolved` resolves. Any other value makes the alert ignored.
`labels`	object	no	Free-form labels, preserved on the incident.
`url`	string	no	Link back to the origin. Also accepted as `externalUrl`.

If status is absent, the alert is treated as a trigger. firing, alerting and resolved are case-insensitive. Any other value — including ok, normal, recovered or closed — is accepted with 202 but ignored: no incident is created or resolved.

Grouping

Repeated sends with the same externalId for the same service are aggregated into the open incident instead of creating duplicates. Use a stable externalId per problem — the job name, the check identifier, the rule key.

If you omit externalId, correlation falls back to a signature computed from the content. Changes to the title or description then produce separate incidents. Send an externalId whenever you can.

Automatic recovery

When the problem is over, send the same externalId with "status": "resolved". aciona.me resolves the incident opened by that source on its own — no person required. Example: a ping monitor opens an incident when the API stops responding and, a few minutes later, reports that it is back.

{
  "status": "firing",
  "externalId": "ping-main-api",
  "title": "Main API is not answering ping",
  "service": "main-api",
  "severity": "critical"
}

{
  "status": "resolved",
  "externalId": "ping-main-api"
}

A recovery only needs status and externalId. Title, description and severity may be sent and may differ from the opening; they are not used to find the incident. service is not needed either. What happens:

The incident moves to resolved from any active state — including after someone acknowledged it or took responsibility for it. Nobody has to approve the resolution in the dashboard.
The timeline records the automatic resolution by the generic webhook, with no person attached. Earlier acknowledgement, owner and history are preserved.
Pending escalations and notifications stop. The recovery does not send a new resolution notice.
The incident is closed automatically 5 minutes after the resolution, as with the other integrations. See Resolve and close.
If the problem comes back — even during those 5 minutes — a new firing opens a new incident.

A recovery requires a valid externalId (non-empty text or a number). Without it the request is rejected with 400 and nothing is stored. aciona.me never resolves by title, service or content signature. To use recovery, send the externalId from the opening onwards.

Good practices and limits

Same key on opening and recovery. The value is compared exactly as sent, with no trimming or case change.
One key per problem. Use different identifiers for different problems or services on the same source: recovery does not use the service to disambiguate.
Correlation is per source. A recovery only resolves incidents opened by the same alert source, in the same organization.
A recovery with no open incident does nothing. The 202 confirms the alert was accepted, not that something was resolved. A repeated recovery is ignored.
Late recovery. If the same key is reused, an old recovery arriving after a new outage may resolve the new occurrence. To avoid it, use one key per episode (for example, ping-main-api-2026-10-15T10:00), stable across that episode’s opening, repeats and recovery.
Ordering under bursts. Under volume spikes, a recovery may be processed before its opening; it then finds nothing and the following trigger stays open. Space out the recovery or resolve it in the dashboard.
Old events are not replayed. Recoveries sent before this feature existed were discarded and do not resolve anything retroactively.

Examples

import os
import requests

requests.post(
    f"https://ingress.aciona.me/webhooks/{os.environ['ACIONA_SOURCE_ID']}",
    headers={"X-Aciona-Token": os.environ["ACIONA_TOKEN"]},
    json={
        "externalId": "daily-backup",
        "title": "Daily backup failed",
        "description": "pg_dump returned code 2",
        "severity": "critical",
        "service": "primary-database",
        "status": "firing",
        "labels": {"env": "prod"},
    },
    timeout=10,
)

await fetch(
  `https://ingress.aciona.me/webhooks/${process.env.ACIONA_SOURCE_ID}`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Aciona-Token': process.env.ACIONA_TOKEN,
    },
    body: JSON.stringify({
      externalId: 'daily-backup',
      title: 'Daily backup failed',
      severity: 'critical',
      service: 'primary-database',
      status: 'firing',
    }),
  },
);

Troubleshooting

Returned 202 but no incident appeared

The status field probably has a value other than firing, alerting or resolved — in which case the alert is accepted and discarded. Send firing or omit the field. If it was a recovery (resolved), it never creates an incident.

The recovery returned 400

The externalId is missing, empty, whitespace-only or not text/number. Send the same externalId used on the opening.

Duplicate incidents

The externalId is changing between sends (for example, by including a timestamp). Use a stable identifier per problem.

Incident with no service or no owner

The service field does not match any service in the organization, or the service has no responsible team with an active schedule.

The recovery did not resolve the incident

Check that the externalId is exactly the same as on the opening and that the recovery was sent to the same source. Incidents opened without an externalId are not reliably resolved by the webhook — resolve them from the dashboard or the app.

Alert sources

Tool guides

Overview

1. Create the alert source

2. Send the alert

Accepted fields

Grouping

Automatic recovery

Good practices and limits

Examples

Troubleshooting

Full payload reference

​Overview

​1. Create the alert source

​2. Send the alert

​Accepted fields

​Grouping

​Automatic recovery

​Good practices and limits

​Examples

​Troubleshooting

Full payload reference

Overview

1. Create the alert source

2. Send the alert

Accepted fields

Grouping

Automatic recovery

Good practices and limits

Examples

Troubleshooting