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-signatureheader? - How do I handle
public_orincident.incident_ created_ v2 schedule.shift_change_v1? - Why does my handler crash on
private_incident.*events (they only contain anid)? - Where is the event data? (
body[body.event_type], notbody.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_); 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_ 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_ | An incident is created |
public_ | An incident is updated |
public_ | An incident's status changes (no private counterpart) |
public_ | A follow-up is created |
private_ | A private incident is created (id only) |
public_ / public_ | An alert fires / resolves |
public_ | An escalation is created |
schedule.shift_change_v1 | The on-call user(s) on a schedule change |
status_ | An 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
- references/overview.md - All 34 events, envelope, private payloads, delivery semantics
- references/setup.md - Create an endpoint, get the Signing secret, IP ranges, replay
- references/verification.md - Signature details, secret decoding, timestamp policy, gotchas