Receive a monitoring tool's webhook · Alert ingest API

POST/ingest/{type}

The endpoint each integration's webhook URL points at, shown with its key in On-Call → Integrations. type selects the parser.

For alerts the body is EvoHub's generic alert (below). For every other type it is the tool's own webhook payload, sent unchanged — a firing alert opens an alert, and where the tool reports recovery, the matching open alert is resolved. Most tools send JSON; UptimeRobot, StatusCake, Site24x7 and PRTG may send form-encoded data (UptimeRobot and StatusCake may also append fields to the URL's query string), and those are read too.

Answers 200 whenever the payload was read, even if it produced no alert, so tools do not disable the webhook; created and resolved say what happened. An AWS SNS subscription confirmation sent to cloudwatch or eventbridge is confirmed automatically and answered with created 0 and a note. SNS deliveries must carry a valid SNS signature.

github, gitlab, jenkins and sonarqube deliveries can be signed: once the integration has a signing secret (On-Call → Integrations, or the On-Call API's signing-secret endpoints), a delivery without a valid signature is refused. GitHub signs with X-Hub-Signature-256, SonarQube with X-Sonar-Webhook-HMAC-SHA256, GitLab sends the secret as X-Gitlab-Token or signs with its signing token, and Jenkins sends it as the Basic auth password or X-EvoHub-Token.

Two more routes live under /ingest: /ingest/api (the Events API, above) and /ingest/email, where EvoHub's mail provider delivers the mail sent to an Email integration's address. You send email to that address; you never call /ingest/email yourself.

Authorization

Requires:

integrationKey

Parameters

Path parameters

type string required
The integration type.
One of: alerts prometheus grafana datadog newrelic cloudwatch azuremonitor dynatrace sentry googlecloud zabbix uptimerobot pingdom site24x7 statuscake nagios prtg cortex opensearch uptimekuma graylog splunk cloudflare instana netdata eventbridge elastic opmanager solarwinds sumologic appdynamics honeycomb wazuh checkmk icinga librenms fortigate github gitlab jenkins sonarqube koi · Example: alerts

Query parameters

key string required
The integration key. eventbridge also accepts it in an X-EvoHub-Key header and honeycomb in X-Honeycomb-Webhook-Token.
Example: YOUR_INTEGRATION_KEY

Request body required

`application/json`

Type: GenericAlert | object

One of:

GenericAlert
Show GenericAlert properties
- title string required
  Example: Disk almost full on web-03
- description string
- status string
  resolved (or resolve, ok, up, online, recovered, closed) resolves the open alert with this fingerprint; anything else, or nothing, opens or retriggers one.
- severity string
  Common synonyms are read too (error and major as high, warning as medium, minor as low, p1–p5); anything else is medium.
  One of: critical high medium low info · Default: medium
- source string
  Stored as the alert's source label; the alert's own source is always webhook.
- fingerprint string
  Deduplicates repeated sends while the alert is open. When omitted, one is derived from the title, the labels and alert_instance/alert_service.
- escalation_policy_id string
  Used only when the integration has no escalation policy of its own.
- labels object
  Other keys: string
- annotations object
  Other keys: string
Native payload
The monitoring tool's own webhook body, for every type except alerts.
Other keys: any

`application/x-www-form-urlencoded`

Type: object

Form-encoded bodies sent by uptimerobot, statuscake, site24x7 and prtg.

Other keys: string

Responses

`200`

The payload was read.

Content type: application/json

Type: IngestResult

data object
- received integer
  Alerts and recoveries found in the payload.
- created integer
  Alerts opened, or matched to an alert already open with the same fingerprint.
- resolved integer
  Recoveries processed.
- test boolean
  Present and true when the delivery was the tool's test notification.
- note string
  Present when the delivery needed no alert work, for example a test notification, an AWS SNS subscription confirmation, or a delivery already processed.
success boolean
Value: true

`400`

The body could not be read as this type's payload (INVALID_BODY); for azuremonitor, the common alert schema is not enabled (INVALID_SCHEMA); for alerts, title is missing, or a resolve has neither fingerprint nor title (VALIDATION_FAILED, with details).

Content type: application/json

Type: Error

error object required
- code string required
  Example: INVALID_KEY
- message string required
  Example: invalid integration key
- details array of object
  Field problems, on VALIDATION_FAILED.
  - field string
  - message string

`401`

key is missing, unknown, or names a disabled integration (INVALID_KEY).

Content type: application/json

Type: Error

error object required
- code string required
  Example: INVALID_KEY
- message string required
  Example: invalid integration key
- details array of object
  Field problems, on VALIDATION_FAILED.
  - field string
  - message string

`403`

For github, gitlab, jenkins and sonarqube: the integration has a signing secret and the delivery carries no signature, or one that does not verify (INVALID_SIGNATURE). For cloudwatch and eventbridge: an SNS message whose SNS signature does not verify (INVALID_SIGNATURE). On any other type: the key belongs to an integration with a signing secret, which only accepts signed deliveries on its own type (SIGNATURE_REQUIRED).

Content type: application/json

Type: Error

error object required
- code string required
  Example: INVALID_KEY
- message string required
  Example: invalid integration key
- details array of object
  Field problems, on VALIDATION_FAILED.
  - field string
  - message string

`413`

The body is larger than 1 MiB (PAYLOAD_TOO_LARGE).

Content type: application/json

Type: Error

error object required
- code string required
  Example: INVALID_KEY
- message string required
  Example: invalid integration key
- details array of object
  Field problems, on VALIDATION_FAILED.
  - field string
  - message string

`500`

The alert could not be stored (INTERNAL_ERROR).

Content type: application/json

Type: Error

error object required
- code string required
  Example: INVALID_KEY
- message string required
  Example: invalid integration key
- details array of object
  Field problems, on VALIDATION_FAILED.
  - field string
  - message string

`503`

The key, the integration's signing secret, or an SNS message's signature could not be checked right now (INGEST_UNAVAILABLE). Retry after the delay given.

Headers

Retry-After integer
Seconds to wait before retrying.

Content type: application/json

Type: Error

error object required
- code string required
  Example: INVALID_KEY
- message string required
  Example: invalid integration key
- details array of object
  Field problems, on VALIDATION_FAILED.
  - field string
  - message string

Example request

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