Trigger alert

Raise an incident from any HTTP-capable system. Same signing model as the ping endpoint.

POST/api/alerts/trigger/{webhookUrl}

{webhookUrl} is the webhook's URL identifier — find it on the webhook detail page in the dashboard.

Headers

FieldTypeDescription
X-Webhook-SignaturerequiredstringHMAC-SHA256 of the request body, hex-encoded, signed with the team webhook secret. See Authentication.
Content-Typerequiredapplication/jsonAlways required.

Body

FieldTypeDescription
titlerequiredstringAlert title, max 200 chars. Shown in Slack and notifications.
descriptionstringLong-form context, max 2000 chars.
severity"sev0" | "sev1" | "sev2" | "sev3" | "sev4"Overrides the webhook default. Drives notification policy routing.
metadataobjectArbitrary key-value payload, max 100 KB, max 10 nesting levels. Available to filter rules.
group_keystringExplicit grouping key, max 200 chars. Identical keys fold into one open alert.

Example request

Build the JSON body, sign it with HMAC-SHA256 using your team webhook secret, and POST the signed bytes.

BODY='{"title":"Deploy failed: api-gateway","description":"Migration step exited with code 137","severity":"sev1","metadata":{"commit":"a1b2c3","environment":"production"},"group_key":"deploy:api-gateway"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$OPSHIFT_SECRET" -hex | awk '{print $2}')
 
curl -X POST https://www.opshift.io/api/alerts/trigger/deploy-failures \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: $SIG" \
  -d "$BODY"

Response

Returns 200 OK. The status field tells you what happened:

json
{
  "alertId": "65f3a2...",
  "status": "created",
  "message": "Alert created",
  "occurrenceCount": 1
}
json
{
  "alertId": "65f3a2...",
  "status": "occurrence_added",
  "message": "Occurrence added to open alert",
  "occurrenceCount": 7
}
json
{
  "alertId": "65f3a2...",
  "status": "reopened",
  "message": "Alert reopened",
  "occurrenceCount": 8
}
json
{
  "status": "filtered",
  "message": "Alert suppressed by filter rule",
  "reason": "metadata.branch != main"
}

Errors

FieldTypeDescription
400Bad requestMissing required field, invalid severity, or metadata exceeded size/nesting limits.
401UnauthorizedMissing or invalid signature.
403ForbiddenTeam subscription expired.
404Not foundUnknown webhook URL or webhook is disabled.
429Too many requestsPer-webhook rate limit or monthly alert quota exhausted.