Send an event · Alert ingest API

POST/ingest/api

Triggers, acknowledges or resolves an alert.

The integration key may be sent as routing_key in the body, as ?key= in the URL, or as Authorization: Bearer <key> — checked in that order.

A trigger needs only a summary; everything else has a default. Acknowledge and resolve find the open alert by dedup_key; when no open alert has that key, nothing happens and the answer is still 202. A trigger without a dedup_key gets one derived from its summary and source, returned in the response — keep it to resolve the alert later. A trigger whose dedup_key matches an open alert does not open a second one; it is recorded as a retrigger on the existing alert.

Authorization

Any one of:

integrationKey
bearerKey
No authentication

Parameters

Query parameters

key string
The integration key, when it is not sent as routing_key or a bearer token.

Request body required

Content type: application/json

Type: EventRequest

An event. The nested payload form and the flat fields are interchangeable; a flat field fills the payload field it names when that one is empty (title is another name for summary).

routing_key string
The integration key.
event_action string
One of: trigger acknowledge resolve · Default: trigger
dedup_key string
Identifies the alert. Required for acknowledge and resolve.
client string
Accepted for Events v2 compatibility; not stored.
client_url string
Accepted for Events v2 compatibility; not stored.
payload EventPayload
Show EventPayload properties
- summary string
  The alert's title. Required for a trigger.
  Example: Database primary is down
- source string
  Where it happened. Stored as the source label.
  Example: db-01.prod.acme.example
- severity Severity
  One of: critical high medium low info error warning · Default: medium
- description string
- timestamp string (date-time)
  Accepted for Events v2 compatibility; the alert is stamped on arrival.
- component string
  Stored as the component label.
- group string
  Stored as the group label.
- class string
  Stored as the class label.
- custom_details object
  Each entry becomes a label, its value as text.
  Other keys: any
summary string
Flat form of payload.summary.
title string
Another name for summary.
severity Severity
One of: critical high medium low info error warning · Default: medium
source string
Flat form of payload.source.
description string
The alert's description.

Responses

`202`

The event was processed.

Content type: application/json

Type: EventAccepted

status, message and dedup_key are sent both at the top level (where Events v2 clients read them) and under data.

status string
Value: success
message string
Example: Event processed
dedup_key string
Example: db-primary-down
data object required
- status string required
  Value: success
- message string required
  Example: Event processed
- dedup_key string required
  The alert's dedup key — the one sent, or the one derived.
  Example: db-primary-down
success boolean required
Value: true

`400`

The body is not JSON, summary is missing on a trigger, dedup_key is missing on an acknowledge or resolve, or event_action is unknown.

Content type: application/json

Type: EventRejected

How /ingest/api answers a request it did not process: success is false, and status, message and errors are sent both at the top level and under data.

status string
Value: invalid event
message string
Example: summary is required
errors array of string
data object
- status string
  Value: invalid event
- message string
  Example: summary is required
- errors array of string
success boolean
Value: false

`401`

No integration key was sent, or it names no enabled integration (or one with a signing secret, which only accepts signed deliveries on its own type).

Content type: application/json

Type: EventRejected

How /ingest/api answers a request it did not process: success is false, and status, message and errors are sent both at the top level and under data.

status string
Value: invalid event
message string
Example: summary is required
errors array of string
data object
- status string
  Value: invalid event
- message string
  Example: summary is required
- errors array of string
success boolean
Value: false

`413`

The body is larger than 1 MiB (PAYLOAD_TOO_LARGE, in the {"error": {code, message}} shape).

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 created, acknowledged or resolved.

Content type: application/json

Type: EventRejected

How /ingest/api answers a request it did not process: success is false, and status, message and errors are sent both at the top level and under data.

status string
Value: invalid event
message string
Example: summary is required
errors array of string
data object
- status string
  Value: invalid event
- message string
  Example: summary is required
- errors array of string
success boolean
Value: false

`503`

The key could not be checked right now. Retry after the delay given.

Headers

Retry-After integer
Seconds to wait before retrying.

Content type: application/json

Type: EventRejected

How /ingest/api answers a request it did not process: success is false, and status, message and errors are sent both at the top level and under data.

status string
Value: invalid event
message string
Example: summary is required
errors array of string
data object
- status string
  Value: invalid event
- message string
  Example: summary is required
- errors array of string
success boolean
Value: false

Example request

curl -X POST 'https://evohub.io/ingest/api?key=<INTEGRATION_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "summary": "Database primary is down",
  "routing_key": "YOUR_INTEGRATION_KEY"
}'