Agent skill

incident.io Webhooks Skill

Receive and verify incident.io webhooks (Standard Webhooks / Svix). Use when setting up incident.io webhook handlers, debugging webhook-signature verification, or handling incident, alert, escalation and on-call events like public_incident.incident_created_v2, public_incident.incident_status_updated_v2, public_alert.alert_created_v1 and schedule.shift_change_v1.

Install this skill

npx skills add hookdeck/webhook-skills --skill 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.

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/, examples/nextjs/, 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.

Payload Envelope and Private Resources

{
  "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.

EventTriggered When
public_incident.incident_created_v2An incident is created
public_incident.incident_updated_v2An incident is updated
public_incident.incident_status_updated_v2An incident's status changes (no private counterpart)
public_incident.follow_up_created_v2A follow-up is created
private_incident.incident_created_v2A private incident is created (id only)
public_alert.alert_created_v1 / public_alert.alert_resolved_v1An alert fires / resolves
public_escalation.escalation_created_v1An escalation is created
schedule.shift_change_v1The on-call user(s) on a schedule change
status_page_incident.update_shared_v1An update is posted on a status page incident

See references/overview.md for the full list of 34 events.

Environment Variables

# 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

# 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


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 17, 2026

View on GitHub →