docs: incident ingest webhook for external alerts

[prabhatsharma]

Documents the incident ingest webhook shipped in openobserve/openobserve#13501 (with openobserve/o2-enterprise#2287). Design rationale: openobserve/o2-enterprise#2286.

What's here

New page — user-guide/analytics/incidents/incident-webhook.md

POST /api/v2/{org_id}/alerts/incidents/ingest accepts alerts from Alertmanager, Datadog, Grafana, or anything that can POST JSON, and correlates them into incidents alongside the alerts OpenObserve evaluates itself.

Sections: endpoint and auth, a working curl, full payload reference, how correlation decides, alert identity and when a delivery notifies, severity mapping, resolve, idempotency, Alertmanager forwarding, viewing external alerts, UI entry point, errors.

Overview link — adds an "Alerts from external systems" subsection to the Incident Management page under Automatic alert correlation, since that's where someone looking for this starts.

Nav — new .pages in incidents/ so the webhook page sits under Incident Management rather than falling to alphabetical order.

Three things the page is deliberate about

• Only labels drives correlation. Stated plainly and repeated, because it's the one thing that determines whether the feature works for a reader. It also explains that semantic field groups normalize instance / host / k8s.node.name, so nobody goes looking for a per-vendor adapter that doesn't exist.
• The Alertmanager example is a transform, not webhook_configs. Alertmanager's native payload is rejected by this endpoint. A webhook_configs snippet would look authoritative and fail with a 400 — so the page shows the jq reshape and says why.
• Resolves carry a warning. Skipping them isn't a silent no-op: incidents stay open for O2_INCIDENTS_AUTO_RESOLVE_AFTER_MINUTES (3 days by default). Called out in an admonition rather than buried.

Verification

mkdocs build --strict could not run here — the repo venv is missing git-revision-date-localized. Validated manually instead:

• Both relative links resolve to real files (index.md, ../alerts/index.md).
• Both in-page anchors (#payload-reference, #severity-mapping) match real headings.
• Both .pages files parse as YAML and reference only files that exist.

Worth a strict build in CI to confirm.

Reviewer notes

The payload reference, severity table, and action values were taken from the implementation rather than the design doc — ExternalAlertPayload::validate, map_external_severity, and ExternalIngestAction in src/config/src/meta/alerts/incidents.rs. Size limits (64 label entries, 1024 chars per key/value, 128-char source, 512-char alert_name, 2048-char external_url) and the 30-minute dedup window are the real enforced values.