Webhooks

A webhook is a write-only alert endpoint scoped to a team. You create one in the dashboard, copy its URL identifier, and post signed JSON to it from anywhere — CI pipelines, queue workers, third-party platforms with outbound webhooks, internal scripts. Each POST either creates a new alert or is folded into an existing one.

Anatomy of a webhook

• URL identifier — a short URL-safe string appended to /api/alerts/trigger/. Treated as a public token; the HMAC signature is what authenticates.
• Default severity — the severity assigned when the POST doesn't specify one. Individual posts can override it.
• Filter rules — Sentry-style conditions evaluated against the incoming payload. A rule can drop the alert or override its severity at the edge.
• Rate cap — optional per-webhook ceiling on alerts per minute.

Triggering an alert

import { OpShift } from "@opshift/sdk";
 
const opshift = new OpShift({ secret: process.env.OPSHIFT_SECRET! });
 
const res = await opshift.alert("deploy-failures", {
  title: "Deploy failed: api-gateway",
  description: "Migration step exited with code 137",
  severity: "sev1",
  group_key: "deploy:api-gateway",
  metadata: {
    commit: "a1b2c3d",
    environment: "production",
    runId: 48211,
  },
});
 
console.log(res.status); // "created" | "occurrence_added" | "filtered" | "reopened"

Field reference

Without the SDK

The SDK is just a convenience wrapper — any HTTP client works. POST signed JSON straight to the trigger endpoint: see Trigger alert for the request, headers, and error reference, and Authentication for how to sign the request body.

Filter rules

Every webhook can carry a list of filter rules — conditions evaluated against the incoming payload. Rules can match nested fields, regex patterns, and combinations of logical operators. A rule either drops the alert (returning filtered with a reason) or overrides its severity.

Example: a CI webhook that ignores alerts from feature branches but keeps anything on main:

IF metadata.branch != "main" THEN drop with reason "non-main branch"

Filters run before any quota or notification work, so dropped payloads cost nothing.

Response shape

{
  "alertId": "65f3...",
  "status": "created",
  "message": "Alert created",
  "occurrenceCount": 1,
  "reason": null
}

For the full status enum and grouping behaviour, see Alerts. For request signing details, see Authentication.

Related