Generic webhook

What it does

The Generic webhook adapter accepts inbound webhook events at /api/integrations/webhook, validates them through its shared handler, normalizes provider payloads, and submits lifecycle events to the configured service.

Prerequisites

An OpsKnight service and enabled integration record.
The integration identifier and generated integration key.
Permission to configure webhooks in Generic webhook.
A network path from the provider to the OpsKnight web runtime.

Setup and configuration

In OpsKnight, open Services → your service → Integrations.
Select Add integration → Generic webhook, then save the integration.
Copy the webhook URL and integration key shown by OpsKnight.
In the sending system, create a webhook for the alerts you want to route.
Use POST and the URL generated by OpsKnight. Configure one of the supported key transports listed below.
Send a test alert, then verify the incident under Incidents.

Provider console labels can change independently of OpsKnight. Use the webhook or notification configuration area in the provider rather than copying a URL from another service. Treat keys and signature secrets as credentials; never place them in logs or source control.

Authentication and request verification

The endpoint requires the integration identifier and validates the integration key using a timing-safe comparison. Signature verification is conditional-when-secret-configured using the generic verification contract. The exact payload schema is defined by src/app/api/integrations/webhook/route.ts and src/lib/integrations/webhook.ts.

Method: POST
Integration identifier: query parameter
Integration key transports: Authorization: Bearer, Authorization: Token token=, x-integration-key, x-api-key, integrationKey query parameter
Schema: shared provider schema
Body limit: 1048576 bytes (1 MiB)
Rate limit: 100 requests per 60 seconds, per integration

Use the payload contract

The adapter emits the lifecycle actions found in its current source:

trigger
acknowledge
resolve Correlation uses the normalized EventPayload.dedup_key; recovery must reuse that same key so the existing incident converges instead of creating another.

Send a stable dedup_key for every update to the same source alert. A minimal trigger is:

json

{
  "summary": "Checkout error rate is high",
  "source": "production-monitor",
  "severity": "critical",
  "status": "triggered",
  "dedup_key": "checkout-error-rate"
}

Resolve it by sending the same dedup_key with "status": "resolved". Use "status": "acknowledged" to acknowledge it. If dedup_key is missing, OpsKnight falls back to id, alert_id, or a value derived from the summary; changing the summary can therefore create a new incident.

Accepted trigger-like values include triggered, fired, alert, critical, error, and open. Resolve-like values include resolved, ok, normal, closed, and fixed. Severity values high, medium, and low map to critical, warning, and info.

Recovery and deduplication

When signature verification runs, the shared handler attempts provider-specific delivery identity before claiming the inbound-delivery fence. Incident convergence still depends on the adapter correlation key. Failed deliveries are recorded for operational inspection without exposing secrets.

Limits and testing

Per-integration rate limiting protects the ingestion path. Send a representative trigger and recovery pair in a non-production service, verify that one incident is created, and confirm that recovery updates that incident rather than creating another.

Verify the connection

After the test alert, confirm all of the following:

One incident appears for the selected OpsKnight service.
The incident source identifies Generic webhook.
A repeat event updates or correlates according to the adapter identity.
A recovery event resolves the correlated incident.

Error reference

400 — Invalid request or payload validation failed.
401 — Integration is disabled, mismatched, or unauthorized.
404 — Integration record was not found.
413 — Payload exceeds the one MiB body limit.
429 — Per-integration request rate exceeded.
503 — A matching delivery is already being processed.

Troubleshooting

Confirm the integration is enabled and belongs to the intended service.
Verify the integration ID in the URL and rotate any key that may have been exposed.
Inspect Settings → Integrations → Failures for validation or signature errors.
Check for 413 before changing payload templates and 429 before retrying rapidly.
Confirm the provider sends a state supported by the event mapping above.
Preserve the provider delivery identifier and timestamp when escalating.

Security

Use HTTPS, rotate exposed keys at both systems, configure signature verification when supported, and restrict provider egress or ingress controls without blocking legitimate retries.