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	—

The generic webhook does not resolve incidents automatically. It always opens or aggregates. If your tool has a dedicated source type (Grafana, Prometheus, Datadog, CloudWatch, Zabbix, New Relic), use that instead — you get auto-resolution and much better field mapping.

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	Stable identifier of the problem. It is the correlation key.
`status`	string	no	`firing` or `alerting`. 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. If it is present with a value other than firing or alerting, the alert is accepted with 202 but no incident is created — including for 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.

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 or alerting — in which case the alert is accepted and discarded. Send firing or omit the field.

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.

How do I resolve the incident?

From the dashboard or the app. The generic webhook does not auto-resolve.

Alert sources

Tool guides

Overview

1. Create the alert source

2. Send the alert

Accepted fields

Grouping

Examples

Troubleshooting

Full payload reference

​Overview

​1. Create the alert source

​2. Send the alert

​Accepted fields

​Grouping

​Examples

​Troubleshooting

Full payload reference

Overview

1. Create the alert source

2. Send the alert

Accepted fields

Grouping

Examples

Troubleshooting