Observability integrations

Update an observability integration

Updates an integration. name, type and preset are required on every call — this endpoint is a replace, not a merge, for those three. Fields with a stored value that you omit entirely are kept (is_active, hmac_enabled, auto_cancel_on_recovery, accumulation_rules, field_mapping, inbox_owner_group_uuid, inbox_digest_interval, the health-check fields, the email settings); sending them as null clears them. Changing health_check_url or health_check_mode resets the probe state so a stale up/down does not linger. The secret is untouched and never returned here; replacing it is a dashboard action (see the secret field of the integration schema). PATCH is accepted on the same path with identical semantics.

put/api/v1/observability/integrations/{integration}

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/{integration}
Auth: API key in header X-API-Key

Path parameters

integrationstring uuid required

Integration UUID.

Request body

namestring required

Display name.

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

Updated integration.

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.