Ingest inbound webhook — StatusDashboard Docs

POST /public/webhooks/inbound

Accepts a signed JSON payload to trigger (create) or update an incident. Processing is asynchronous — a 200 response means the request was queued. Check inbound webhook logs for the final processed or processing_failed outcome.

Requires a valid webhook signing key (see Create webhook key). The organization must have the integrations feature enabled.

Authentication uses HMAC headers — not a Bearer token. See the Inbound Webhooks platform guide for signature format and examples.

Request headers

Header	Required	Description
`Content-Type`	Yes	`application/json`
`X-SD-Key-Id`	Yes	Webhook key ID (e.g. `wk_a1b2c3d4e5f6a7b8`)
`X-SD-Signature`	Yes	`t=<unix_seconds>,v1=<hmac_sha256_hex>`
`X-SD-Idempotency-Key`	No	Optional dedupe key for `action: "trigger"` (must match `idempotencyKey` in the body when both are sent)

Request body

Discriminated union on action.

`action: "trigger"` — create incident

Field	Type	Required	Description
`action`	`"trigger"`	Yes	Create operation
`title`	string	Yes	1–250 characters
`description`	string	Yes	1–5000 characters
`impactAnalysis`	string	No	Optional customer and service impact details. Rich text field. See Rich text fields. Max 5,000 characters.
`severity`	string	Yes	Event-level severity label
`componentIds`	string[] (UUID)	Yes	1–20 affected component IDs
`statusLabel`	string	No	Initial workflow phase
`initialMessage`	string	No	First timeline message
`idempotencyKey`	string	No	Optional dedupe key for this trigger (see platform guide)
`notifications`	boolean	No	Default `true`
`segmentNotification`	object	No	Segment targeting (requires segments feature)
`attributes`	array	No	Custom attributes

`action: "update"` — advance incident

impactAnalysis is not accepted on update actions. Set it on trigger, or use PATCH /app/events/{id} to change it later.

Field	Type	Required	Description
`action`	`"update"`	Yes	Update operation
`eventId`	string (UUID)	Yes	Event to update
`statusLabel`	string	Yes	Workflow phase to advance to
`message`	string	Yes	Timeline message (1–5000 characters)
`notifications`	boolean	No	Toggle notifications on the event
`segmentNotification`	object	No	Update segment targeting
`attributes`	array	No	Replace attributes

Sample request

TS=$(date +%s)
BODY='{"action":"trigger","title":"API errors","description":"Elevated 5xx","severity":"Major Outage","componentIds":["b2c3d4e5-f6a7-8901-bcde-f12345678901"],"notifications":true}'
SIG=$(echo -n "${TS}.${BODY}" | openssl dgst -sha256 -hmac "$SD_SIGNING_SECRET" | awk '{print $2}')

curl -X POST https://api.statusdashboard.com/public/webhooks/inbound \
  -H "Content-Type: application/json" \
  -H "X-SD-Key-Id: $SD_KEY_ID" \
  -H "X-SD-Signature: t=${TS},v1=${SIG}" \
  -d "$BODY"

Sample response

Status: 200 OK (queued)

{ "ok": true }

Status: 400 Bad Request (schema validation)

{ "error": "..." }

Authentication failures return 200 { "ok": true } intentionally. If events are not appearing, verify your Key ID, signing secret, and webhook logs.

Error responses

Status	When
`200`	Request accepted and queued (`{ "ok": true }`). Also returned for some authentication failures by design — check inbound webhook logs for outcomes.
`400`	JSON parse failure, schema validation error, or semantic rejection before queueing.
`429`	Organization inbound rate limit exceeded (logged as `rate_limited` when authenticated).