Events API · Docs · Pulseback

Anything that can make an HTTP request can raise an incident: Prometheus Alertmanager, Grafana, CI, a script. The Events API takes the same body as PagerDuty’s Events API v2, so tools that already speak it only need a new URL and routing key.

Setup

In Integrations, add an Events API integration. Choose the escalation policy it pages and a default severity.
Copy its integration key. That’s your routing_key.
Send events to:

POST https://app.pulseback.io/api/v1/events
Content-Type: application/json

No other authentication is needed: the routing key identifies the integration. Rotate it from the integration’s settings if it leaks.

Request body

Field	Type	Required	Notes
`routing_key`	string	yes	The integration key, 10–100 characters.
`event_action`	string	yes	`trigger`, `acknowledge` or `resolve`.
`dedup_key`	string	for `acknowledge` / `resolve`	Up to 255 characters. Events with the same key belong to the same incident. Omit it on `trigger` and one is generated and returned.
`payload`	object	for `trigger`	What happened. Fields below.
`links`	array	no	Up to 10 `{ "href": "https://…", "text": "…" }` links shown on the incident.

`payload`

Field	Type	Required	Notes
`summary`	string	yes	The incident title, 1–1024 characters. Keep the useful part first.
`source`	string	no	Where it happened: a host, service or URL.
`severity`	string	no	`critical`, `error`, `warning` or `info`. Default `error`.
`component`	string	no	The part of the system affected, e.g. `postgres`.
`group`	string	no	A logical grouping, e.g. `prod-datapipe`.
`class`	string	no	The kind of event, e.g. `disk-full`.
`custom_details`	object	no	Any JSON object, kept with the alert on the incident.

Fields Pulseback doesn’t use (images, client, client_url and so on) are ignored, so existing Events v2 senders work unchanged.

Severity mapping

`severity`	Pulseback severity
`critical`	`sev1` (SEV-1)
`error`	`sev2` (SEV-2)
`warning`	`sev3` (SEV-3)
`info`	`sev4` (SEV-4)

Response

A valid event returns 202 Accepted:

{ "status": "success", "dedup_key": "db-replica-lag", "incident_id": "inc_8Kd2…" }

Errors use the standard error body. A malformed event gets 400 with error.code validation and the problems in error.details. Retry 429 and 5xx responses with backoff.

Behaviour

Trigger opens an incident and starts its escalation policy. Another trigger with the same dedup_key while the incident is open is grouped into it as a new alert, without paging again.
Acknowledge acknowledges the open incident with that dedup_key and stops escalation.
Resolve resolves it.

Examples

Trigger

curl -X POST https://app.pulseback.io/api/v1/events \
  -H "Content-Type: application/json" \
  -d '{
    "routing_key": "'"$PULSEBACK_ROUTING_KEY"'",
    "event_action": "trigger",
    "dedup_key": "db-replica-lag",
    "payload": {
      "summary": "Replica lag above 30s on db-2",
      "source": "db-2.internal",
      "severity": "critical",
      "component": "postgres",
      "group": "prod-db",
      "class": "replication",
      "custom_details": { "lag_seconds": 41, "primary": "db-1" }
    },
    "links": [{ "href": "https://grafana.example.com/d/db", "text": "DB dashboard" }]
  }'

Resolve

curl -X POST https://app.pulseback.io/api/v1/events \
  -H "Content-Type: application/json" \
  -d '{ "routing_key": "'"$PULSEBACK_ROUTING_KEY"'", "event_action": "resolve", "dedup_key": "db-replica-lag" }'

Prometheus Alertmanager

Alertmanager’s PagerDuty receiver sends Events v2. Point it at Pulseback:

receivers:
  - name: pulseback
    pagerduty_configs:
      - routing_key: <your integration key>
        url: https://app.pulseback.io/api/v1/events
        severity: '{{ if eq .CommonLabels.severity "page" }}critical{{ else }}warning{{ end }}'

Moving from PagerDuty

Change the endpoint from PagerDuty’s to https://app.pulseback.io/api/v1/events and replace the routing key with a Pulseback integration key. The body stays the same. See Pulseback vs PagerDuty.