# incident.io Webhooks

incident.io (incident management and on-call) sends webhooks from **Settings → Webhooks**. Delivery
runs on Svix and follows the Standard Webhooks spec, with the spec-neutral `webhook-` header prefix:
`webhook-id`, `webhook-timestamp` and `webhook-signature` (not `svix-*`). Each delivery is a JSON `POST`;
return any 2xx to acknowledge it. There is no handshake or challenge.

This skill covers the Settings → Webhooks product only. Workflow "HTTP request" steps are a separate
feature that leaves from different IPs and doesn't use this signing scheme.

## When to Use This Skill

* How do I receive incident.io webhooks?
* How do I verify the incident.io `webhook-signature` header?
* How do I handle `public_incident.incident_created_v2` or `schedule.shift_change_v1`?
* Why does my handler crash on `private_incident.*` events (they only contain an `id`)?
* Where is the event data? (`body[body.event_type]`, not `body.data`)
* Why is my incident.io webhook signature verification failing?

## Verification (core)

Signed content is `{webhook-id}.{webhook-timestamp}.` followed by the **raw body bytes**. HMAC-SHA256,
standard base64 digest. `webhook-signature` holds space-delimited `v1,<base64>` entries (several during
a secret rotation); accept if any `v1` entry matches. Key: a `whsec_<base64>` secret is base64-decoded
after the prefix, any other value is used as UTF-8 bytes.

```javascript
import crypto from 'node:crypto';

function secretToKey(s) {
  if (!s) return Buffer.alloc(0);
  if (!s.startsWith('whsec_')) return Buffer.from(s, 'utf8');
  const encoded = s.slice('whsec_'.length);
  // Buffer.from(x, 'base64') skips invalid characters, so check the alphabet first
  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(encoded)) return Buffer.alloc(0);
  return Buffer.from(encoded, 'base64');
}

const key = secretToKey(process.env.INCIDENT_IO_WEBHOOK_SECRET);
// id/ts/sig = webhook-id / webhook-timestamp / webhook-signature headers; rawBody = Buffer
if (key.length === 0 || !/^[1-9]\d*$/.test(ts)) throw new Error('Bad secret or timestamp');
const expected = Buffer.from(
  crypto.createHmac('sha256', key).update(`${id}.${ts}.`).update(rawBody).digest('base64')
);
const valid = sig.split(' ').some((entry) => {
  const comma = entry.indexOf(',');
  if (comma === -1 || entry.slice(0, comma) !== 'v1') return false; // version tag must be exactly v1
  const received = Buffer.from(entry.slice(comma + 1)); // compare base64 text, don't decode
  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
const body = JSON.parse(rawBody.toString('utf8')); // only after valid === true
const resource = body[body.event_type]; // the key IS the event type string

```

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/incident-io-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/incident-io-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/incident-io-webhooks/examples/fastapi/).

The examples verify by hand rather than with the `svix` / `standardwebhooks` libraries. incident.io has
no SDK of its own, those libraries hardcode a 5-minute timestamp window, and the hand-written version
handles both secret forms (and rejects a `whsec_` value that isn't valid base64). The timestamp is signed, so the replay window is optional
(`INCIDENT_IO_WEBHOOK_TOLERANCE_SECONDS`); deduplicate on `webhook-id` either way. See
[references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/incident-io-webhooks/references/verification.md).

## Payload Envelope and Private Resources

```json
{
  "event_type": "public_incident.incident_created_v2",
  "public_incident.incident_created_v2": { "id": "01FDAG4SAP5TYPT98WGR2N7W91", "name": "Our database is sad", "...": "..." }
}

```

Route on `event_type` (there is no event-type header) and read the resource from `body[event_type]`.
**Private** incidents, alerts and escalations send only `{ "id": "abc123" }`. Call the incident.io API
with a key that has private access to get the details. The two `private_incident.membership_*` events
are the exception: they carry `incident_id`, `user_id` and `actor_user_id`.

## Common Event Types

All 34 event names carry a `_vN` version suffix that is part of the name.

| Event | Triggered When |
| --- | --- |
| `public_incident.incident_created_v2` | An incident is created |
| `public_incident.incident_updated_v2` | An incident is updated |
| `public_incident.incident_status_updated_v2` | An incident's status changes (no private counterpart) |
| `public_incident.follow_up_created_v2` | A follow-up is created |
| `private_incident.incident_created_v2` | A private incident is created (id only) |
| `public_alert.alert_created_v1` / `public_alert.alert_resolved_v1` | An alert fires / resolves |
| `public_escalation.escalation_created_v1` | An escalation is created |
| `schedule.shift_change_v1` | The on-call user(s) on a schedule change |
| `status_page_incident.update_shared_v1` | An update is posted on a status page incident |

See [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/incident-io-webhooks/references/overview.md) for the full list of 34 events.

## Environment Variables

```bash
# app.incident.io > Settings > Webhooks > your endpoint > Signing secret
INCIDENT_IO_WEBHOOK_SECRET=whsec_xxxxx
# Optional replay window in seconds (unset = no window)
# INCIDENT_IO_WEBHOOK_TOLERANCE_SECONDS=86400

```

## Local Development

```bash
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 incident-io --path /webhooks/incident-io

```

Add the tunnel URL as an endpoint under **Settings → Webhooks** and copy its Signing secret.

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/incident-io-webhooks/references/overview.md) - All 34 events, envelope, private payloads, delivery semantics
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/incident-io-webhooks/references/setup.md) - Create an endpoint, get the Signing secret, IP ranges, replay
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/incident-io-webhooks/references/verification.md) - Signature details, secret decoding, timestamp policy, gotchas