Observability integrations

Create an observability integration

Creates an inbound alert source and returns it together with the one and only copy of its secret.

The response carries everything needed to start sending alerts: endpoint_url is the absolute URL to POST to, and secret is the credential for it. Send the secret as X-WardenPoint-Secret: <secret> or as Authorization: Bearer <secret>; AWS CloudWatch integrations may also pass it as a ?secret= query parameter, because SNS cannot set headers. The endpoint answers 202 on success, 401 on a wrong secret, 403 while is_active is false, and 413 above the body-size cap.

Set hmac_enabled: true and the plain-secret header stops working entirely. Signed requests then need two headers: X-WardenPoint-Timestamp with the current Unix time, and X-WardenPoint-Signature with the lowercase hex hmac_sha256("<timestamp>.<raw body>", secret). The timestamp must be within 300 seconds of server time and each signature is accepted once. GitHub integrations are the exception: they always use GitHub's own X-Hub-Signature-256 scheme with the same secret, regardless of this flag.

The secret exists in plaintext only in this response — it is stored hashed. If you lose it, rotate it. The response is NOT idempotent: repeating this call creates a second integration with a second secret.

An integration created here is active unless you say otherwise, so it accepts alerts immediately. Without recipient_group_uuid and without routing rules an accepted alert is recorded and lands in the triage inbox but pages nobody — attach a group, or add routing rules, to have it reach people.

Passing recipient_group_uuid creates a catch-all routing rule pointing at that group. It is a real rule, listed by the routing-rules endpoint, and it stays last: rules you add afterwards are inserted above it, so building the routing table in a second step works as written. If you would rather have no default route at all, omit the field and create your rules explicitly.

The email type is only creatable when the operator has enabled email-to-alert; otherwise the call answers 403.

post/api/v1/observability/integrations

Request

  • Base URL: https://wardenpoint.com (the document declares no server; this is the origin it was published from)
  • URL: https://wardenpoint.com/api/v1/observability/integrations
  • Auth: API key in header X-API-Key

Request body

namestring required

Display name.

type'generic_webhook' | 'grafana' | 'prometheus_alertmanager' | 'datadog' | 'cloudwatch' | 'zabbix' | 'uptime_kuma' | 'sentry' | 'kibana' | 'github' | 'gitlab' | 'email' required

Payload shape the integration parses. generic_webhook accepts a flat JSON object with external_alert_id, title, severity, status, source_url (and can be re-pointed with field_mapping). grafana and prometheus_alertmanager accept the native Alertmanager webhook body. datadog, cloudwatch (SNS), zabbix, uptime_kuma, sentry, kibana, github, gitlab accept those tools' native webhook bodies (gitlab parses merge request events only and is available when the operator has enabled the GitLab integration). email has no webhook at all — it receives mail at inbound_email_address and is only available when the operator has enabled email-to-alert.

preset'notify_every_alert' | 'burst_protection' | 'critical_only' | 'digest_only' | 'custom_rules' required

Starting accumulation policy, expanded into accumulation_rules on save. notify_every_alert — every occurrence notifies. burst_protection — notify below 5-in-10-minutes, escalate at the threshold, stay quiet after. critical_only — ignore everything but critical, escalate immediately. digest_only — stay quiet until 5 occurrences in 10 minutes, then one message. custom_rules — take accumulation_rules from the request instead. Send notify_every_alert if you want the very first alert to be delivered.

is_activeboolean

Defaults to true on create — an integration created over the API is live immediately. Send false explicitly to create it switched off; while off the alert endpoint answers 403. Omitting it on update keeps the stored value.

recipient_group_uuidstring uuid nullable

Group to page for alerts of this integration. ON CREATE this is not just a stored field: it also creates a real, visible routing rule named "Catch-all (migrated default)" that matches every alert and points at the group, so the integration pages somebody from the first alert on. That rule is listed by GET /observability/integrations/{integration}/routing-rules like any other and can be edited or deleted. It is always kept LAST, and every rule you add afterwards is inserted above it — a narrower rule added later still wins. ON UPDATE the field only re-points the group; no rule is created, and if the catch-all still exists it keeps pointing where it did. Omit or send null to create no rule at all, in which case unmatched alerts stay in the triage inbox and nobody is paged. The dashboard-only sentinel __self__ is rejected here — an API key has no user to build a personal group from.

hmac_enabledboolean

Turn on signed requests. Doing so INVALIDATES the plain-secret header path — see the create endpoint description for the signature scheme. Defaults to false on create; omitting it on update keeps the stored value, so a partial update never quietly stops verifying signatures.

auto_cancel_on_recoveryboolean

Cancel an in-flight escalation when the matching alert resolves. Defaults to true on create; omitting it on update keeps the stored value.

field_mappingobject nullable

Generic webhook only: canonical field to dot-path in your JSON, e.g. {"title": "alert.name", "severity": "labels.level"}. Unmapped fields fall back to the default key chain. Omitting the field on update keeps the stored mapping; send the paths you want to drop as empty strings to clear it.

inbox_owner_group_uuidstring uuid nullable

Group owning the triage inbox. Omitting the field on update keeps the stored value; sending null clears it.

inbox_digest_intervalinteger nullable

Minutes between inbox digests. 0 disables.

email_correlation'smart' | 'per_email' nullable

Email type only: smart collapses a firing message and its later recovery into one alert by normalised subject; per_email makes every message a standalone alert. Defaults to smart.

email_sender_allowliststring[] nullable

Email type only: allowed sender addresses or domains. Sending [] clears the list, omitting the field keeps it.

health_check_mode'off' | 'active' | 'heartbeat' nullable

off, active (we GET health_check_url) or heartbeat (your tool calls us and silence means down).

health_check_urlstring uri nullable

Target of the active probe. Must resolve to a public address — private and loopback targets are rejected.

health_heartbeat_grace_secondsinteger nullable

Heartbeat mode: silence tolerated before the integration is called down. 30..86400, default 180.

Example request

{
  "name": "Prometheus prod"
}

Response

Integration created; data.secret holds the only copy of the secret.

Example response

{
  "data": {
    "routing_rules": [
      {
        "label_matchers": [
          {
            "key": "service",
            "value": "checkout"
          }
        ]
      }
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.