Generic webhook integration

Any system that can POST JSON over HTTPS can send alerts to Unit Oncall. You point it at a Webhook URL, and a transformation rule maps your custom payload into Unit Oncall's normalized alert format. Use this when there is no dedicated guide for your source (the dedicated guides — Datadog, Grafana, Alertmanager, CloudWatch, GitHub Actions — are just generic webhooks with a ready-made mapping).

Setup

1. In Unit Oncall, create a Webhook (Integrations → Webhooks → New). Choose a Team and default Schedule.
2. Pick an auth mode:
   • Standard — the secret is embedded in the URL token, so the URL is self-contained. Use this when your sender can only POST to a URL and cannot add headers.
   • Secure — the secret is sent separately as the X-Webhook-Secret header or a webhook_secret body field. Use this when your sender can attach a header.
3. Copy the generated Webhook URL and configure your source system to POST its alert JSON to it.
4. Create a transformation rule that maps your payload's fields onto Unit Oncall's targets, and bind it to the Webhook. See Recommended transformation rule below.

If you do not attach a transformation rule, Unit Oncall reads same-named top-level keys from your payload as a fallback (fingerprint, title, message, severity, timestamp, tags). Sending a body shaped exactly like those keys works without any mapping — but a transformation rule is what lets you adapt an arbitrary payload.

Webhook URL

Unit Oncall exposes a single unified receive endpoint. The token in the path identifies the webhook (and, in Standard mode, carries the secret), so there is no separate Authorization header:

POST https://<your-api-host>/api/v1/wh/{token}

• {token} is an opaque, encrypted value generated when you create the Webhook. Treat it as a credential and keep it out of public logs.
• A successful receive returns 202 Accepted — Unit Oncall queues the alert and processes it asynchronously.
• Send Content-Type: application/json with a JSON object body.

Example request (Secure mode, secret in a header):

POST https://<your-api-host>/api/v1/wh/{token}
Content-Type: application/json
X-Webhook-Secret: <your-secret>

{ "incident_id": "db-12", "summary": "Replica lag high", "level": "high", "detected_at": "2026-06-05T12:00:00Z" }

Recommended transformation rule

A transformation rule maps fields out of your payload onto Unit Oncall's targets. Each mapping has a type:

• jsonpath — extract a value with a JSONPath expression (for example $.incident_id, $.alerts[0].labels.name). Optionally add a mapping table to translate the extracted value, and a default for when extraction yields nothing.
• format — build a string from one or more {$.path} placeholders, for example "[{$.level}] {$.summary}".
• static — a fixed value.

fingerprint, title, severity, and message are required — if any resolves to empty, the receive is rejected with 400. timestamp and tags are optional. Map timestamp to your source's detection time whenever it exists so state transitions are ordered correctly.

The example below maps a simple custom payload:

{
  "name": "Generic webhook",
  "description": "Maps a custom JSON payload to Unit Oncall alerts.",
  "is_active": true,
  "mappings": {
    "fingerprint": {
      "type": "jsonpath",
      "path": "$.incident_id"
    },
    "title": {
      "type": "format",
      "format": "[{$.level}] {$.summary}"
    },
    "severity": {
      "type": "jsonpath",
      "path": "$.level",
      "mapping": {
        "high": "critical",
        "medium": "warning",
        "low": "info"
      },
      "default": "warning"
    },
    "message": {
      "type": "jsonpath",
      "path": "$.summary",
      "default": "Alert received (no summary provided)"
    },
    "timestamp": {
      "type": "jsonpath",
      "path": "$.detected_at"
    },
    "tags": {
      "type": "jsonpath",
      "path": "$.tags"
    }
  }
}

See the Transformation Rule reference for every field, the full mapping syntax, and array handling (delimiters and trim characters) for tags.

Troubleshooting

• No alert arrives. Confirm the request returned 202 Accepted, the Webhook is enabled, and the URL token is complete.
• 403 webhook disabled. The Webhook's is_enabled is false. Enable it.
• 400 bad request. The token is malformed, or in Secure mode the secret is missing/wrong (X-Webhook-Secret header or webhook_secret body field).
• Fields are empty after mapping. A JSONPath did not match your payload. Verify the exact key names and nesting; remember array indexing like $.alerts[0] and wildcards like $.items[*].
• Severity is always the default. The source value was missing or not in the mapping table. Add the value or rely on default.
• Alerts resolve/re-open out of order. Map timestamp to your source's detection time; otherwise Unit Oncall falls back to the receive time. See the note in the Transformation Rule reference.