Webhook reference

Every inbound webhook adapter — URL forms, the fields each one reads, how service, severity, status and identity are derived, the response counters, correlation rules and the exact error strings.

Reference · Updated 2026-10-27 · Describes release 0.1.164

Exact facts about the inbound webhook plane, one section per adapter. For the walkthroughs that set a sender up, read Alerts from your observability platform and Alert sources and intake rules; this page is what those pages point at when a field, a mapping or an error string matters.

URL forms and authentication

POST https://<your-host>/webhook/<source>/<workspace-slug>
POST https://<your-host>/webhook/<source>/<workspace-slug>/<token>

<source> is one of the adapter names below. alertmanager, generic and change are their own routes; every other source is served by one shared adapter route, except kubernetes-audit, whose only path form ends in the cluster name and takes the cluster's own audit token.

The credential is the workspace's webhook token, read in this order; the first one present wins:

Only the SHA-256 hash of the token is stored. A bad slug, a disabled workspace, a workspace that has never minted a token and a wrong token all answer the same 401 invalid webhook credentials, so nothing about the workspace leaks to whoever posts at it. Minting a new token (Alert intake & tokens → Webhook ingest → Mint webhook token, pillars.manage) invalidates the previous one immediately; there is no overlap window.

A token that travels in one of the platform's own intake URLs — the path segment after the slug, or a token= query value — is redacted as [REDACTED:secret] before an alert, a change or a finding is stored.

Rate limit

A per-workspace token bucket over alert items (or change events), not HTTP requests: one payload may carry a whole storm. The limit is aiops_ingest_rate_per_min (platform default 1200 items per minute, one minute of burst; a workspace value of 0 or less switches it off). When the bucket is dry the whole payload is refused with 429 and a Retry-After header in seconds, so a sender that honours Retry-After redelivers everything and nothing is silently dropped. The refusal is audited as ingest.rate_limited at most once a minute per workspace.

Response body

Every alert endpoint answers the same counter set, whatever the source. The two scanner-specific counters are present as 0 for ordinary alert sources, so never assert on an exact key set.

Change-carrying deliveries answer {"recorded": N, "flagged_unauthorized": M} instead — no alert counters (see Change sources). A source that has a change extractor but no alert adapter answers {"recorded": 0} when the payload yields no change event. An SNS SubscriptionConfirmation answers {"confirmed": true|false}.

Canonical labels and workspace maps

Every adapter produces alert items of one shape: fingerprint, status (firing or resolved), labels, annotations, starts_at and the raw payload. The canonical labels every later stage reads:

Four workspace settings rewrite labels before deduplication, in this order:

1. label_map {"source_key": "canonical_key"} renames label keys. The hook that makes a source with its own vocabulary correlate with everything else (for example {"FunctionName": "service"}).
2. severity_map {"source_value": "canonical"} rewrites the severity value when it matches exactly.
3. source_service_labels {"<source>": ["<label>", …]} (what the Unidentified service — map this source card saves) names the service of an alert from that source that still carries no service: the first listed label the alert carries is copied onto service; an alert's own service is never replaced, and no other source is touched.
4. service_alias {"<alert service>": "<dependency-map service>"} (the Service aliases card) is the last step: an alert whose service is listed takes the dependency map's name, so it keys, folds and reads its blast radius there; the original stays as service_original. One hop, never a chain (see Service aliases).

All four are workspace settings set with PATCH /api/aiops/{tenant_id} (members.manage); source_service_labels also has its card under Alert intake & tokens → Intake rules → Mapped sources, and service_alias its Service aliases card below it. The Settings reference lists their shapes and checks.

Identity, grouping and storms

Dedupe is by fingerprint: an item whose fingerprint is active on an open incident is counted as deduped and dropped, whatever its labels say. Every adapter below states what its fingerprint is made of.

Grouping key is the strongest of service=<v>, namespace=<v>, alertname=<v> the item carries, in that order, within one pillar; an item with none of them keys on fingerprint=<fp> and never groups. There is no time window: an alert joins the open incident with its key regardless of age. The first alert of an incident is correlated, later ones suppressed.

Pillar routing: severity: security routes to SecOps; a finding_family label routes threat-detected to SecOps and every other family to Compliance; a source, labels.source or labels.tool value of guardduty, securityhub, falco, trivy, wazuh or crowdstrike (case-insensitive) routes to SecOps; everything else is Incident and Problem. The pillar is part of the grouping bucket, so a Falco alert for payments-api never joins the telemetry incident for the same service.

Grouping by the service graph: an alert that would open (or reopen) an incident for a service whose dependents already have open incidents (opened or reopened inside aiops_storm_group_window_s + aiops_storm_spread_window_s, 900 s) opens it and takes theirs in, over edges allowed to fold (a caller's analysis waits up to aiops_storm_group_window_s for its dependency's alert, unless it is a P1); with aiops_storm_agent on (the default) one bounded turn later groups related incidents over every recorded edge. A burst of unrelated services opens one incident each (an alert name already firing on 3 services still joins their incident, aiops_fold_shared_cause_threshold); there is no storm threshold and no __storm__ incident since 0.1.147. The rules and the review steps are in Alert storm: grouped by the service graph.

Holds at ingest: an alert naming no service opens its own held unmapped=<fp> incident when aiops_unmapped_triage is on; so does a ServiceNow, Jira or Azure DevOps ticket that does not name every field in ticket_required_fields (the platform asks on it once, see Tickets that come in must name five fields); an alert with neither a service-ish label nor an alertname is held when aiops_require_identity_labels is on; a built-in detection warning rule opens its incident with no run. Held incidents wait in the triage queue for Analyse.

Reopen: when aiops_reopen_window_h is above 0, an alert whose key matches an incident resolved inside the window reopens that incident instead of opening a new one; aiops_flap_threshold reopens inside the window mark it flapping. Storm and fingerprint keys never reopen, and neither does an incident a person closed as known noise.

Priority is derived at open and re-derived on every change of severity, blast radius or criticality: critical → P1, error → P2, warning → P3, anything else → P4; one level up (floor P1) when the computed blast radius reaches two services (failing dependents grouped in count since 0.1.147), and one more for a mission-critical resource. The owner a new incident opens with comes from assignment_map {"<service glob>": "<assignee>"}: the first pattern matching the alert's service (its namespace when there is no service).

Alertmanager

POST /webhook/alertmanager/<workspace-slug> — the standard Alertmanager webhook body, the highest-fidelity path: labels and annotations pass through verbatim.

Configure the receiver with send_resolved: true and the token through http_config.authorization (type Bearer). A payload with no alerts list answers 200 with "received": 0.

Generic

POST /webhook/generic/<workspace-slug> — {source, alerts: [{fingerprint, status, labels, annotations, message, startsAt}]}. You control every canonical field.

CloudWatch via SNS

POST /webhook/cloudwatch-sns/<workspace-slug>[/<token>] — the SNS notification envelope whose Message is the alarm JSON as a string; with RawMessageDelivery the alarm JSON may be the whole body. SNS cannot set a header, so the token rides in the path. The SubscriptionConfirmation handshake is answered automatically on any /webhook/<source> path; only an https://sns.<region>.amazonaws.com SubscribeURL is ever fetched.

Point the alarm's OK action at the same topic or nothing ever closes. Set treat_missing_data to notBreaching on metrics that legitimately go idle; the Probable cause card never calls a change proven good on an alarm that can be OK on silence.

Azure Monitor

POST /webhook/azure-monitor/<workspace-slug>[/<token>] — the common alert schema; the adapter reads data.essentials and a payload without it yields no alert. Dynamic-threshold rules send the same essentials and attribute the same way; alertContext is not read.

Enable auto-resolve on the alert rule so Resolved is actually sent. For scope-targeted rules, label_map: {"resource": "service"} attributes at resource granularity.

Grafana

POST /webhook/grafana/<workspace-slug> — Grafana unified alerting's Alertmanager-shaped body. Mapping as Alertmanager, with label values coerced to strings. A multi-dimensional rule emits one alert per series; the series label that identifies the workload must be mapped onto service in the rule or through label_map. Leave Disable resolved message off.

Datadog

POST /webhook/datadog/<workspace-slug> — a monitor webhook with the custom payload template:

{"alert_id": "$ALERT_ID", "id": "$ID", "alert_scope": "$ALERT_SCOPE",
 "title": "$ALERT_TITLE", "body": "$EVENT_MSG", "alert_type": "$ALERT_TYPE",
 "alert_transition": "$ALERT_TRANSITION", "tags": "$TAGS", "date": "$DATE"}

Enable the webhook on both the alert and the recovery transitions.

Dynatrace

POST /webhook/dynatrace/<workspace-slug> — a problem notification from a Custom integration (or a Workflow) with the JSON template whose {ImpactedEntities} and {ProblemDetailsJSONv2} placeholders stay unquoted. A Dynatrace problem is already a correlated incident, so one problem is one alert, never one per entity.

Send test notification posts the template with sample values and is answered 200 with "received": 1, "alerts_created": 1 and one incident on service MyService1; resolve that incident by hand unless a RESOLVED for the same test PID follows. A 400 request body is not JSON on this path usually means a string placeholder was left unquoted.

Robusta

POST /webhook/robusta/<workspace-slug> — a webhook_sink finding, including the Kubernetes-native findings (CrashLoopBackOff, OOMKill, ImagePullBackOff) that never reach Alertmanager.

Always firing: Robusta emits no resolved transition, so closure comes from another source clearing, a remediation or a person.

Security Hub

POST /webhook/securityhub/<workspace-slug>[/<token>] — ASFF findings delivered by EventBridge (detail.findings), by SNS (a JSON string in Message), posted directly as {"findings": [...]}, or as a bare finding with an Id or Title. Findings are normalised into the compliance shape; one finding of a shape the platform does not model is skipped, not the whole delivery.

The finding_family label routes a threat-detected family (GuardDuty) to SecOps and every other family to Compliance; an AWS Config rule is never a threat, whatever service its name mentions (guardduty-enabled-centralized checks that GuardDuty is on). Forward PASSED / RESOLVED too or the clear never arrives. The same findings can be pulled on a schedule instead (aiops_scanner_sync_interval_s, Security posture → Posture → Scanner sync); pull and webhook share the deduplication.

Defender for Cloud

POST /webhook/defender/<workspace-slug> — assessments or security alerts pushed by workflow automation (a Logic App HTTP action): a bare object, or a findings, value, assessments or alerts list, optionally under data. Normalised into the same shape as Security Hub, so one compliance path serves both clouds. Keep the Healthy state in the automation's filter so the clear arrives.

ServiceNow

POST /webhook/servicenow/<workspace-slug> — an outbound REST message from a business rule. ServiceNow has no fixed webhook schema; the record is read from record, resource or the flat body, and each field may be a string or a {display_value, value} pair (name-like fields read the display value, priority and state read the code).

A record whose sys_class_name starts with change_request, or whose number starts with CHG, is a change and goes to the change ledger instead.

Jira

POST /webhook/jira/<workspace-slug> — jira:issue_created and jira:issue_updated only; comment events (the platform's own RCA write-back included) yield nothing.

An issue whose type name contains change goes to the change ledger instead.

Azure DevOps

POST /webhook/azure-devops/<workspace-slug> — service hooks. workitem.created and workitem.updated are signals; git.push and git.pullrequest.merged are changes; every other event type yields nothing.

workitem.updated is read from the work item as it now is (resource.revision.fields, id resource.workItemId). A state change is a signal. An edit of System.Tags, System.AssignedTo, Severity, Priority, System.Description, Microsoft.VSTS.TCM.ReproSteps or System.AreaPath only moves on a work item held for missing fields (Tickets that come in must name five fields) and otherwise yields nothing; any other update — a comment, the platform's own write-back — yields nothing.

Change sources

A change never opens an incident. These sources write rows to the change ledger — the answer to what changed last on this service, ranked on the incident's Probable cause card and flagged when it falls in a freeze window — and answer {"recorded": N, "flagged_unauthorized": M}. Rows dedupe per source and id, so a redelivered hook is harmless.

A servicenow or jira change ticket accounts for a captured write (unauthorized-change detection) only when it arrives with the workspace's ITSM webhook token instead of the shared one; see Changes.

kubernetes-audit has its own path form, /webhook/kubernetes-audit/<workspace-slug>/<token>/<cluster-name>, because the API server's webhook client drops the query string; with the token in a header, put - in the token segment. Its credential is that cluster's audit token (POST /api/aiops/{workspace}/k8s-audit-token/<cluster-name>, see the audit webhook), never the webhook token: what it posts is recorded as the platform's own audit trail. The shared form (/webhook/kubernetes-audit/<workspace-slug>, with or without ?cluster=) answers 404.

Service resolution for every change row: the event's own service, else the workspace change_service_map {"<repo glob>": "<service>"}, else unmapped (recorded, listed under ''); change_resource_map {"<resource glob>": "<service>" | ["<service>", …]} only adds linked services.

Your own change feed

POST /webhook/change/<workspace-slug>[/<token>] with {"source": "<name>", "events": [...]}; each event carries kind (push, pr_merged, deploy, sync or config) and any of service, repo, ref, sha, id, author, title, url, at, detail. An empty or missing events list is 400 payload must carry a non-empty 'events' list. Events count against the rate limit like alerts.

kind: "config" is a setting changed inside an application: service names the application, id is the application's own audit-row id (deduped per source, service and id), detail is {key, old?, new?, resource_id?, service?}. Values are protected by the key's name only: under a key that looks secret (password, secret, token, key, pass, pwd, dsn, auth, cert, salt, bearer) only key, resource_id and service are kept and old/new read [not stored]; a URL's scheme://user:password@host password is replaced in every kept value. Never send a credential in a change payload.

Test alerts and receipts

Because the public endpoint answers one generic 401, the way to learn whether a sender reached the platform is a validation session: Alert intake & tokens → Send a test alert mints a correlation id, the sample payload carries it as the aiops_validation label with service aiops-validation, and the ingest stamps a receipt onto the session in the same transaction as the alert. Samples exist for alertmanager, generic, datadog and dynatrace; any other source is 422 no sample for '<source>' yet. A session expires after 24 hours.

The page also reports attribution_state — service, namespace, alertname or fingerprint — naming which label grouped the alert; anything but service means real alerts from that sender will not join the right incident.

Errors

A 413 can also come from an ingress or proxy in front of the platform before the request reaches it: ingress-nginx refuses bodies over its proxy-body-size (1 MiB by default).

Next steps

• Next: Settings reference
• All Reference pages
• Documentation home