Skip to main content
Use Generic Webhook when an alert source can send an outbound HTTP request but does not have a first-class OpenCluster integration. The sender must produce the canonical schema; OpenCluster does not run field mappings or transformations.

​
Prerequisites

  • Network access from the sender to the OpenCluster intake endpoint over HTTPS.
  • A sender that can set the X-OpenCluster-Token header and send JSON.
  • The Admin role in OpenCluster.

​
Least-privilege access

The sender needs permission only to reach its generated webhook URL and read the one-time secret. The credential authenticates this Integration only; it is not a product API credential.

​
Connect

Create a Generic Webhook integration, then copy its webhook URL and one-time secret. Send each alert to that URL with the secret in X-OpenCluster-Token.
Use the same eventId, startedAt, and deduplicationKey for the matching resolution, set status to resolved, and add resolvedAt. Repeating the same phase is safe. Reusing an eventId with different content in the same phase returns 400.

​
Schema limits

Unknown or duplicate fields, invalid UTF-8, trailing JSON, and an Organization identifier are rejected. Annotation text is displayed as untrusted source content. OpenCluster never fetches sourceUrl during intake.

​
Verify

Send one firing event and confirm the response is 202 Accepted. Open the matching Alert Event and Incident. An exact retry should return 200 OK without creating another lifecycle phase. When a firing event opens a new Incident and a model provider is configured, acceptance also queues its automatic Investigation. Without a model provider, the Alert Event and Incident are still recorded but no Investigation is created. Updates to the same Incident do not open another Investigation.

​
Evidence available

The Alert Event supplies its title, severity, lifecycle timestamps, labels, annotations, deduplication key, and optional source URL. It creates Incident context but does not let OpenCluster read the sender or the linked source URL during an Investigation.

​
Limitations

Generic Webhook performs no field mapping or enrichment. The sender must preserve one stable lifecycle identity and canonical schema. Connect a separate evidence Integration when an Investigation needs runtime, change, or conversation data.

​
Delivery responses

​
Troubleshooting

  • 400: validate the canonical fields, lifecycle identity, timestamps, and body size.
  • 401: check the Integration ID and current secret; rotate it if the stored value is uncertain.
  • 503: retry with bounded backoff, honor Retry-After when present, and preserve the same lifecycle identity. Pending Investigation capacity refusals record no part of the event and include Retry-After; accepted duplicates and Incident updates still succeed at full capacity.

​
Rotate, disable, or remove

Rotate the webhook secret, store the replacement immediately, and update the sender before its next delivery. Rotation invalidates the old value. Disable the Integration to stop new deliveries while retaining history. Deletion is refused when retained records depend on it.

​
Next step

Connect an evidence source, then run the first Investigation from a test Alert Event.

​
Availability

Generic Webhook is available in OSS v0.1 and has no third-party provider mark.