# Ingest inbound webhook

Create or update an incident via a signed public webhook request.

Source: https://statusdashboard.com/docs/api/integrations/webhooks/inbound/post

`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](/docs/api/integrations/webhooks/inbound/logs/list) for the final `processed` or `processing_failed` outcome.

Requires a valid webhook signing key (see [Create webhook key](/docs/api/integrations/webhooks/inbound/keys/create)). The organization must have the **integrations** feature enabled.

Authentication uses HMAC headers — not a Bearer token. See the [Inbound Webhooks platform guide](/docs/integrations/webhooks/inbound) 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](/docs/api#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
```bash
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)

```json
{ "ok": true }
```

**Status: `400 Bad Request`** (schema validation)

```json
{ "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](/docs/api/integrations/webhooks/inbound/logs/list) 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).                                                                                                                  |