# Guide to incident.io Webhooks: Features and Best Practices

[incident.io](https://incident.io) runs incident response, on-call and status pages for engineering teams. Its webhooks tell your other systems when something changes: an incident is declared or changes status, a follow-up is created, an alert fires, an escalation changes status, or the on-call user on a schedule changes. Teams use them to annotate dashboards, mirror follow-ups into their issue tracker, keep a data warehouse up to date, or drive their own automation.

This guide covers incident.io's 34 event types and their unusual payload envelope, private incidents that only send an ID, setting up an endpoint, verifying the signature, and the delivery behaviour to plan for.

## What are incident.io webhooks?

You create webhook endpoints in incident.io under **Settings → Webhooks**. Each endpoint has a URL, the event types it receives, and its own **Signing secret**. From the same page you can send test events, see recent deliveries and retry failed ones.

incident.io's webhooks are delivered by Svix and follow the Standard Webhooks format. Every request carries `webhook-id`, `webhook-timestamp` and `webhook-signature` headers, and the signature is an HMAC of the ID, the timestamp and the raw body.

Workflow steps that send HTTP requests are a separate feature. They send whatever you configure in the workflow, leave from different IP addresses and aren't signed this way. This guide covers the webhooks in Settings → Webhooks.

## incident.io webhook features

| Feature | Details |
| --- | --- |
| Configuration | **Settings → Webhooks**, one or more endpoints |
| Event selection | Per endpoint, from 34 event types |
| Signature | Standard Webhooks HMAC-SHA256, base64 encoded |
| Headers | `webhook-id`, `webhook-timestamp` (Unix seconds), `webhook-signature` |
| Secret | One **Signing secret** per endpoint |
| Body | `{"event_type": "...", "<event_type>": {...}}` |
| Event routing | Body field `event_type`. No header carries it |
| Private resources | ID only |
| Success | Any `2xx` |
| Retries | Exponential backoff over 24 hours |
| Disabling | After repeated failures over 5 days, with an email |
| Ordering | Not guaranteed |
| Replay and testing | Test events, delivery log, retry and replay in Settings → Webhooks |
| Source IPs | [Published](https://docs.incident.io/admin/webhook-ips), and available from `GET /v1/ip_ranges` |
| HIPAA | Not compliant, and excluded from incident.io's BAA |

## Events and payloads

Every body has exactly two keys: `event_type`, and a second key whose name is the event type itself, dots included. The resource sits under that second key:

```json
{
  "event_type": "public_incident.incident_created_v2",
  "public_incident.incident_created_v2": {
    "id": "01FDAG4SAP5TYPT98WGR2N7W91",
    "reference": "INC-123",
    "name": "Our database is sad",
    "visibility": "public",
    "incident_status": { "name": "Closed", "category": "triage" },
    "severity": { "name": "Minor", "rank": 1 },
    "permalink": "https://app.incident.io/incidents/123"
  }
}

```

This is shortened from incident.io's example, which also includes the creator, custom fields, role assignments, timestamps and Slack channel details. There is no `data` key, and no event ID or timestamp in the body: read the resource with `body[body.event_type]`, and use the `webhook-id` header as the delivery ID.

### Private incidents, alerts and escalations

For private incidents, alerts and escalations, incident.io sends only the resource ID, so private details don't reach systems that shouldn't see them:

```json
{
  "event_type": "private_incident.incident_created_v2",
  "private_incident.incident_created_v2": { "id": "abc123" }
}

```

To get the details, call the incident.io API with an API key that has private access. The two `private_incident.membership_*` events are the exception: they carry `incident_id`, `user_id` and `actor_user_id`.

### Event types

The version suffix (`_v1` or `_v2`) is part of the event name. You choose a version by subscribing to that name.

| Event | Triggered When | Common Use Cases |
| --- | --- | --- |
| `public_incident.incident_created_v2` | An incident is created | Open a ticket, annotate a graph |
| `public_incident.incident_updated_v2` | An incident is updated | Sync severity, summary and custom fields |
| `public_incident.incident_status_updated_v2` | An incident's status changes | Track time to resolution |
| `public_incident.follow_up_created_v2` | A follow-up is created | Mirror it into your issue tracker |
| `public_incident.follow_up_updated_v2` | A follow-up is updated | Update the mirrored issue |
| `public_incident.postmortem_document_status_updated_v1` | A postmortem's status is updated | Chase overdue postmortems |
| `public_alert.alert_created_v1` | An alert is created | Correlate alerts with deploys |
| `public_alert.alert_resolved_v1` | An alert is resolved | Close the matching record |
| `public_escalation.escalation_created_v1` | An escalation is created | Page a secondary system |
| `public_escalation.escalation_status_updated_v1` | An escalation changes status | Record acknowledgement times |
| `schedule.shift_change_v1` | The on-call user(s) on a schedule change | Update an on-call directory or Slack topic |
| `status_page_incident.update_shared_v1` | An update is posted on a status page incident | Post the update to other channels |

The full list is in incident.io's [machine-readable webhook spec](https://docs.incident.io/openapi/webhooks.json), which includes a complete example body for each type. It also has `schedule.created_v1`, `schedule.updated_v1` and `schedule.deleted_v1`, the `v1` follow-up events, and `private_*` versions of the incident, follow-up, postmortem, alert and escalation events. `incident_status_updated_v2` has no private version, and the membership events have no public one.

Four of the event pairs look like one event under two names. `public_incident.action_created_v1` and `public_incident.follow_up_created_v1` have the same description and the same example body, and the same goes for `action_updated_v1` and the two private pairs. incident.io doesn't say whether one replaces the other, or whether one change sends one delivery or two. Subscribe to one spelling. If you take both public spellings, deduplicate on the follow-up `id` plus `updated_at`, not the `id` alone, which every later update of the same follow-up shares. The private versions carry only the `id`, so subscribe to one spelling there.

> **See incident.io payloads before you write a handler.** Point an endpoint at a [Hookdeck Inspect](https://inspect.hookdeck.com) URL and send a test event from its settings to see the exact headers and body, with no account or setup required.

## Setting up incident.io webhooks

1. In incident.io, go to **Settings → Webhooks** and add an endpoint.
2. Enter your HTTPS URL, for example `https://example.com/webhooks/incident-io`.
3. Choose the event types to send. Only subscribe to `private_*` events if your receiver can fetch private resources from the API.
4. Save, then copy the endpoint's **Signing secret** into `INCIDENT_IO_WEBHOOK_SECRET`.
5. Send a test event and check that your endpoint returns a `2xx`.

incident.io's docs don't show the secret's format. Standard Webhooks secrets usually start with `whsec_`, followed by a base64 key. Keep exactly what the dashboard shows: the verifiers below handle both forms.

For local testing, start a tunnel with the [Hookdeck CLI](/docs/cli) and use its URL for the endpoint:

```bash
npx hookdeck-cli listen 3000 incident-io --path /webhooks/incident-io

```

**With Hookdeck.** Create a source with the **incident.io** type, paste the endpoint's Signing secret into **Webhook Signing Secret**, and use the source URL as the endpoint URL. Verification is optional on this source, so without a secret every request is accepted. Hookdeck base64-decodes a `whsec_` secret and uses any other value as plain text, the same as the verifiers below. The source accepts `POST` only. Requests that fail verification still get a `200` from Hookdeck, but they're recorded as failed and never reach your service.

## Securing incident.io webhooks

incident.io publishes the signed content as `$WEBHOOK_ID.$WEBHOOK_TIMESTAMP.$REQUEST_BODY` and refers to Svix's manual verification instructions for the rest. Putting the two together:

1. Build the signed content: `webhook-id`, a dot, `webhook-timestamp`, a dot, then the raw body bytes.
2. Get the key. If the secret starts with `whsec_`, base64-decode what follows. Otherwise use the secret's UTF-8 bytes.
3. Compute HMAC-SHA256 and encode it as standard base64.
4. Split `webhook-signature` on spaces. Each entry is `v1,<base64>`, and there can be more than one during a secret rotation. Accept the request if any `v1` entry matches, using a constant-time comparison.

```javascript
const crypto = require('node:crypto');

function signingKey(secret) {
  if (typeof secret !== 'string' || secret === '') return null;
  if (!secret.startsWith('whsec_')) return Buffer.from(secret, 'utf8');
  const encoded = secret.slice('whsec_'.length);
  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(encoded)) return null;
  const key = Buffer.from(encoded, 'base64');
  return key.length > 0 ? key : null;
}

function verifyIncidentIoWebhook(rawBody, headers, secret) {
  const key = signingKey(secret);
  const id = headers['webhook-id'];
  const timestamp = headers['webhook-timestamp'];
  const signature = headers['webhook-signature'];
  if (!key || !Buffer.isBuffer(rawBody)) return false;
  if (typeof id !== 'string' || id === '' || typeof signature !== 'string') return false;
  if (typeof timestamp !== 'string' || !/^[1-9][0-9]*$/.test(timestamp)) return false;

  const expected = Buffer.from(
    crypto
      .createHmac('sha256', key)
      .update(`${id}.${timestamp}.`, 'utf8')
      .update(rawBody)
      .digest('base64'),
    'utf8',
  );
  // The header can hold several space-separated `v1,<base64>` values during a secret rotation.
  return signature.split(' ').some((entry) => {
    const comma = entry.indexOf(',');
    if (comma === -1 || entry.slice(0, comma) !== 'v1') return false;
    const received = Buffer.from(entry.slice(comma + 1), 'utf8');
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

```

Verify the raw bytes before parsing, then read the resource from the key named after the event type. Store the event and answer quickly:

```javascript
const express = require('express');

const app = express();

app.post('/webhooks/incident-io', express.raw({ type: '*/*' }), async (req, res) => {
  if (!verifyIncidentIoWebhook(req.body, req.headers, process.env.INCIDENT_IO_WEBHOOK_SECRET)) {
    return res.sendStatus(401);
  }

  let body;
  try {
    body = JSON.parse(req.body.toString('utf8'));
  } catch {
    return res.sendStatus(400);
  }
  const eventType = body && typeof body.event_type === 'string' ? body.event_type : null;
  // The resource sits under a key named after the event type, not under `data`.
  const resource = eventType && Object.hasOwn(body, eventType) ? body[eventType] : null;
  if (!resource || typeof resource !== 'object') return res.sendStatus(400);

  try {
    await queue.add('incident-io', { webhookId: req.headers['webhook-id'], eventType, resource });
  } catch {
    return res.sendStatus(503); // not stored, so let incident.io retry
  }
  return res.sendStatus(204);
});

```

`queue` is a placeholder for your job queue.

The same check in Python:

```python
import base64
import binascii
import hashlib
import hmac
import re

TIMESTAMP = re.compile(r"[1-9][0-9]*")

def signing_key(secret):
    if not secret:
        return None
    if not secret.startswith("whsec_"):
        return secret.encode("utf-8")
    try:
        key = base64.b64decode(secret[len("whsec_"):], validate=True)
    except (binascii.Error, ValueError):
        return None
    return key or None

def verify_incident_io_webhook(raw_body: bytes, headers, secret) -> bool:
    key = signing_key(secret)
    msg_id = headers.get("webhook-id")
    timestamp = headers.get("webhook-timestamp")
    signature = headers.get("webhook-signature")
    if not key or not msg_id or not signature or not timestamp:
        return False
    if not TIMESTAMP.fullmatch(timestamp):
        return False
    signed = f"{msg_id}.{timestamp}.".encode("utf-8") + raw_body
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest())
    for entry in signature.split(" "):
        version, _, received = entry.partition(",")
        if version == "v1" and hmac.compare_digest(received.encode("utf-8"), expected):
            return True
    return False

```

In FastAPI, pass `await request.body()` and `request.headers`, which look names up case-insensitively.

These verifiers check the signature but not the timestamp's age. incident.io doesn't publish a tolerance, and the Svix and Standard Webhooks libraries reject timestamps more than five minutes from the current time. That window rejects any delivery that is held and sent later with its original headers, such as a Hookdeck retry or replay. Because the timestamp is part of the signed content it can't be altered, so deduplicating on `webhook-id` is enough to stop a captured request being processed twice. If you add an age check for direct traffic, make it longer than incident.io's 24-hour retry period.

> **Make incident.io webhooks production-ready.** [Hookdeck Event Gateway](/event-gateway) verifies every incident.io webhook with your Signing secret, queues each incident and on-call change durably, and retries delivery to your service on a schedule you control.

## Keeping another system in sync

incident.io delivers webhooks individually and doesn't guarantee their order. Its recommendation is to treat each webhook as a prompt: receive it, fetch the latest state from the API, and save that. The same approach covers private resources, which only send an ID. A worker for the queued events above might look like this:

```javascript
async function fetchIncident(incidentId) {
  const response = await fetch(
    `https://api.incident.io/v2/incidents/${encodeURIComponent(incidentId)}`,
    { headers: { Authorization: `Bearer ${process.env.INCIDENT_IO_API_KEY}` } },
  );
  if (!response.ok) throw new Error(`incident.io API returned ${response.status}`);
  const { incident } = await response.json();
  return incident;
}

async function handleIncidentIoEvent({ eventType, resource }) {
  switch (eventType) {
    case 'public_incident.incident_created_v2':
    case 'public_incident.incident_updated_v2':
    case 'private_incident.incident_created_v2': // carries only { id }
    case 'private_incident.incident_updated_v2':
      return saveIncident(await fetchIncident(resource.id));
    case 'public_incident.incident_status_updated_v2':
      return saveIncident(await fetchIncident(resource.incident.id));
    case 'schedule.shift_change_v1':
      return updateOnCall(resource.schedule, resource.current_users);
    default:
      return undefined; // subscribed but not handled yet
  }
}

```

`saveIncident` and `updateOnCall` stand in for your own code. Create the API key under **Settings → API keys**, and give it private incident access if you subscribe to `private_incident.*` events. Because the worker always stores the latest state, an out-of-order or repeated webhook can't overwrite newer data.

## incident.io webhook limitations and pain points

### The resource isn't under `data`

**The Problem:** A handler that works for other providers finds no data in incident.io webhooks.

**Why It Happens:** The resource sits under a key named after the event type, such as `"public_incident.incident_created_v2"`, which changes with every event.

**Workarounds:**

* Read `body[body.event_type]`, with bracket access in JavaScript because the key contains dots.
* Reject bodies where that key is missing.

**How Hookdeck Can Help:** Hookdeck [filters](/docs/filters) can route on `event_type`, so each family of events reaches the right handler, and a [transformation](/docs/transformations) can move the resource under a fixed key before delivery.

### Private events only carry an ID

**The Problem:** Code that reads `.name` or `.severity` gets `undefined`, or crashes on nested fields, for some incidents.

**Why It Happens:** Private incidents, alerts and escalations send only `{ "id": "..." }` so private details don't leak to other systems.

**Workarounds:**

* Fetch the resource from the incident.io API with a key that has private access, as in the worker above.
* If you don't need private incidents, don't subscribe to the `private_*` events.

**How Hookdeck Can Help:** Filters can send `private_*` events to a separate destination that holds the privileged API key, keeping it away from services that don't need it.

### Events arrive out of order

**The Problem:** An incident's update arrives before its creation, or an older status overwrites a newer one.

**Why It Happens:** incident.io delivers each webhook individually over HTTPS and retries failures, so it can't guarantee order.

**Workarounds:**

* Fetch the latest state from the API rather than applying the payload as-is.
* If you apply payloads directly, compare `updated_at` with what you've stored and ignore older versions.

**How Hookdeck Can Help:** Hookdeck keeps every event with its arrival time, so you can see the sequence incident.io actually sent and replay events after fixing a handler.

### Downtime can disable your endpoint

**The Problem:** Webhooks stop arriving after an outage on your side.

**Why It Happens:** incident.io retries with exponential backoff for 24 hours. If deliveries keep failing over a 5-day period, it disables the endpoint and emails you.

**Workarounds:**

* Watch for the email, fix your service, then check the endpoint in Settings → Webhooks and replay the messages you missed.
* Reconcile open incidents with the API after any long outage.

**How Hookdeck Can Help:** Hookdeck accepts each webhook as soon as it arrives, so incident.io sees successful deliveries while your service is down. Hookdeck then delivers to your service with [retries](/docs/retries) you configure, and [issues](/docs/issues) alert you when those deliveries fail.

### Duplicate follow-up event names

**The Problem:** You can't tell whether subscribing to both spellings gives you one follow-up change twice, or whether subscribing to one misses changes.

**Why It Happens:** The `action_created_v1` and `follow_up_created_v1` families (and their `_updated_` versions) have the same descriptions and example bodies. incident.io doesn't say whether one replaces the other, or whether one change sends one delivery or two.

**Workarounds:**

* Subscribe to one spelling, preferably `follow_up_*_v2`, which adds `title`, `priority`, `labels`, `creator` and `assignee_team` and drops the `v1` `follow_up` boolean.
* If you subscribe to both public `v1` spellings, deduplicate on the follow-up `id` plus `updated_at`. Both fields are in each body and match across the pair, while the `id` alone would also drop genuine later updates. The private versions carry only the `id`, so take one spelling there.

**How Hookdeck Can Help:** Hookdeck [deduplication](/docs/deduplication) drops repeated events within a time window, comparing the fields you choose. Put a [transformation](/docs/transformations) first that moves the resource under a fixed key, then compare on the follow-up `id` and `updated_at`, so both spellings of one change match but later updates still get through.

### Not covered by the BAA

**The Problem:** A team under a Business Associate Agreement can't send PHI through webhooks.

**Why It Happens:** incident.io states its webhooks aren't currently HIPAA compliant and are excluded from its BAA.

**Workarounds:**

* Keep PHI out of incident names, summaries and custom fields, or don't use webhooks for incidents that might contain it.
* Check with incident.io before relying on any webhook for regulated data.

## Best practices

### Verify the raw body first

Use `express.raw()`, `await request.text()` in a Next.js route handler, or `await request.body()` in FastAPI. Parsing and re-serialising the JSON changes the bytes and breaks the signature.

### Acknowledge fast and process asynchronously

Verify, store the event and return `2xx`, then call the API and update other systems in a worker. See [why to process webhooks asynchronously](/webhooks/guides/why-implement-asynchronous-processing-webhooks).

### Deduplicate on `webhook-id`

Retries and replays can deliver the same message more than once, and the body has no event ID of its own. Store `webhook-id` before acting. See our [guide to webhook idempotency](/webhooks/guides/implement-webhook-idempotency).

### Allowlist IPs from the API, not by hand

If your endpoint sits behind a firewall, read the webhook addresses from `GET /v1/ip_ranges`, which needs no API key and labels which traffic uses each range. Svix operates these addresses, and incident.io can't promise notice before they change. Workflow HTTP steps use different addresses.

### Rotate secrets without downtime

During a rotation `webhook-signature` can hold more than one `v1` entry. A verifier that accepts any matching entry keeps working while you switch secrets.

## Conclusion

incident.io's webhooks cover incidents, follow-ups, alerts, escalations, on-call schedules and status pages, signed in the Standard Webhooks format. The details that catch people out are the envelope, where the resource sits under a key named after the event type, and private events that carry only an ID. Verify the raw body against the Signing secret, deduplicate on `webhook-id`, fetch the latest state from the API rather than trusting the order of delivery, and keep your endpoint healthy so incident.io doesn't disable it.

[Hookdeck Event Gateway](https://hookdeck.com) verifies each incident.io webhook, keeps every event, and retries and replays delivery to your service, so an outage on your side doesn't mean a missed incident update.

[Get started with Hookdeck](https://dashboard.hookdeck.com/signup) for free and handle incident.io webhooks reliably in minutes.