Incident subscriptions

Incident subscriptions deliver a JSON payload to your target_url when an incident is created, marked investigating, or resolved. They use the same delivery headers as webhook integration subscriptions.

Deliveries use a 10-second timeout (same as other integration subscriptions).

Event types

Create one subscription per event type you care about (or three if you want all lifecycle events).

Create subscription

POST /v1/incident-subscriptions

curl -s -X POST \
  "https://api.hookdeploy.dev/v1/incident-subscriptions" \
  -H "Authorization: Bearer hd_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_url": "https://hooks.example.com/hookdeploy-incidents",
    "platform": "custom",
    "event_type": "incident.created"
  }'

Body fields:

Subscriptions are scoped to the API key. Creating again for the same key + platform + event type upserts the target_url.

Response (not wrapped in a data envelope):

{
  "id": "55555555-5555-5555-5555-555555555555",
  "organization_id": "66666666-6666-6666-6666-666666666666",
  "platform": "custom",
  "event_type": "incident.created",
  "target_url": "https://hooks.example.com/hookdeploy-incidents",
  "active": true,
  "created_at": "2026-05-24T12:00:00Z"
}

List subscriptions

GET /v1/incident-subscriptions

Returns active subscriptions for the calling API key.

curl -s "https://api.hookdeploy.dev/v1/incident-subscriptions" \
  -H "Authorization: Bearer hd_live_YOUR_KEY"

Delete subscription

DELETE /v1/incident-subscriptions/:id

Returns HTTP 204 with no body.

curl -s -X DELETE \
  "https://api.hookdeploy.dev/v1/incident-subscriptions/SUBSCRIPTION_ID" \
  -H "Authorization: Bearer hd_live_YOUR_KEY"

Delivery payload

Each delivery is a JSON object:

Example:

{
  "incident_id": "11111111-1111-1111-1111-111111111111",
  "status": "open",
  "scope": "destination",
  "destination_name": "Production Server",
  "asn_org": null,
  "likely_cause": "Forwards to Production Server are failing",
  "failure_count": 3,
  "endpoint_count": 1,
  "organization_id": "66666666-6666-6666-6666-666666666666",
  "event_type": "incident.created",
  "occurred_at": "2026-05-24T12:00:00.000Z"
}

Delivery headers

Every delivery includes:

content-type: application/json
x-hookdeploy-event: incident.created
x-hookdeploy-subscription-id: {subscription-id}
x-hookdeploy-delivery-timestamp: {ISO-8601}

These match the headers used for webhook integration subscription deliveries (/v1/subscriptions).

Sample and recent helpers

For editor testing (Zapier polling samples, etc.):

event_type must be one of incident.created, incident.investigating, incident.resolved.

Error responses

Next steps

• Incidents API — List, update, and replay incidents
• Incidents concept — How incidents are correlated
• Zapier integration / n8n integration — Managed REST Hook clients