Alert API and generic webhook

If your tool is not in the catalog, or you want to raise alerts from your own code, use the API integration. It accepts a small JSON body in which only a summary is required, and it can also acknowledge and resolve alerts. Its body is compatible with the Events v2 shape used by other paging tools, so a tool that already speaks it only needs a new URL and key.

#Set up the API integration

#Send an event

POST https://evohub.io/ingest/api with a JSON body. Send the integration key in whichever way your tool makes easiest:

• "routing_key" in the body,
• ?key= in the URL, or
• an Authorization: Bearer <key> header.

curl -X POST 'https://evohub.io/ingest/api' \
  -H 'Authorization: Bearer YOUR_INTEGRATION_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"summary": "Database primary is down"}'

curl -X POST 'https://evohub.io/ingest/api' \
  -H 'Content-Type: application/json' \
  -d '{
    "routing_key": "YOUR_INTEGRATION_KEY",
    "event_action": "trigger",
    "dedup_key": "db-primary-down",
    "payload": {
      "summary": "Database primary is down",
      "source": "db-01.prod.acme.example",
      "severity": "critical",
      "component": "postgres",
      "group": "payments",
      "custom_details": { "region": "eu-central" }
    }
  }'

curl -X POST 'https://evohub.io/ingest/api' \
  -H 'Content-Type: application/json' \
  -d '{
    "routing_key": "YOUR_INTEGRATION_KEY",
    "event_action": "resolve",
    "dedup_key": "db-primary-down"
  }'

#Request fields

You can send the alert details nested in payload (Events v2 style) or as flat fields at the top level. A flat field fills the matching payload field when that one is empty.

#Response

A processed event returns 202:

{
  "data": {
    "status": "success",
    "message": "Event processed",
    "dedup_key": "db-primary-down"
  },
  "success": true
}

Keep the dedup_key if you let EvoHub derive it — you need it to resolve the alert later.

A request that was not processed returns the same envelope with "status": "invalid event" and a message:

#How events behave

• Trigger opens an alert and starts the integration's escalation policy. A trigger whose dedup_key matches an alert that is still open does not open a second one; it is recorded as Retriggered on the existing alert.
• Acknowledge acknowledges the open, triggered alert with that dedup_key.
• Resolve resolves the open alert with that dedup_key.
• Acknowledging or resolving a dedup_key that has no open alert does nothing and still returns 202.
• The integration's escalation policy always applies; the request cannot choose another one.

#Generic alert webhook

EvoHub also accepts a simpler, flat alert format at /ingest/alerts. Use it with the key of your API integration:

curl -X POST 'https://evohub.io/ingest/alerts?key=YOUR_INTEGRATION_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Disk almost full on web-03",
    "description": "/var is at 93%",
    "severity": "high",
    "source": "cron-disk-check",
    "fingerprint": "web-03-disk-var",
    "labels": { "host": "web-03.acme.example" },
    "annotations": { "runbook": "https://wiki.acme.example/disk" }
  }'

The key goes in ?key= only. A missing title returns 400 with the code VALIDATION_FAILED and the field in details; a bad key returns 401 with INVALID_KEY. A successful call returns 200 with {"data": {"received": 1, "created": 1, "resolved": 0}, "success": true}. This format cannot acknowledge or resolve; use the API events above for that.

#Tips

• Choose a stable dedup_key (or fingerprint) per problem, such as <host>-<check>, so repeats while the problem lasts do not open new alerts and your resolve finds the right alert.
• Send a resolve when your check passes again. Without one, the alert stays open until someone resolves it.
• Only new alerts count toward usage; retriggers of an open alert do not. See How billing works.

#Related

• Integrations overview
• Alerts and incidents
• Escalation policies