Incidents API

The Incidents API exposes correlated forward-failure incidents for your organization. See Incidents for how correlation, status, and replay work.

Mutating routes (PATCH, replay) require an API key whose creator has super_admin, admin, or developer role.

List incidents

GET /v1/incidents

curl -s "https://api.hookdeploy.dev/v1/incidents?status=open&limit=25" \
  -H "Authorization: Bearer hd_live_YOUR_KEY"

Query parameters:

Response:

{
  "data": {
    "data": [
      {
        "id": "11111111-1111-1111-1111-111111111111",
        "status": "open",
        "scope": "destination",
        "destination_id": "990e8400-e29b-41d4-a716-446655440004",
        "destination_name": "Production Server",
        "asn": null,
        "asn_org": null,
        "likely_cause": "Forwards to Production Server are failing",
        "failure_count": 12,
        "endpoint_count": 2,
        "first_failure_at": "2026-05-24T12:00:00Z",
        "last_failure_at": "2026-05-24T12:15:00Z",
        "is_recurring": false,
        "previous_incident_id": null,
        "resolved_at": null,
        "investigating_at": null
      }
    ],
    "meta": {
      "count": 1,
      "has_more": false,
      "next_cursor": null
    }
  }
}

When data.meta.has_more is true, pass data.meta.next_cursor as before for the next page.

Get incident

GET /v1/incidents/:id

Returns the incident plus nested failures (up to 100, newest first) and updates (newest first).

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

Response (shape abbreviated):

{
  "data": {
    "id": "11111111-1111-1111-1111-111111111111",
    "status": "investigating",
    "scope": "destination",
    "destination_name": "Production Server",
    "likely_cause": "Forwards to Production Server are failing",
    "failure_count": 12,
    "endpoint_count": 2,
    "investigating_at": "2026-05-24T12:20:00Z",
    "resolved_at": null,
    "failures": [
      {
        "request_id": "770e8400-e29b-41d4-a716-446655440002",
        "endpoint_id": "550e8400-e29b-41d4-a716-446655440000",
        "destination_id": "990e8400-e29b-41d4-a716-446655440004",
        "destination_url": "https://myserver.com/webhooks",
        "status_code": 502,
        "error": null,
        "failed_at": "2026-05-24T12:15:00Z",
        "replayed_at": null,
        "replay_status_code": null
      }
    ],
    "updates": [
      {
        "id": "22222222-2222-2222-2222-222222222222",
        "body": "Status changed to investigating",
        "is_system": true,
        "author_id": "33333333-3333-3333-3333-333333333333",
        "created_at": "2026-05-24T12:20:00Z"
      }
    ]
  }
}

Update status

PATCH /v1/incidents/:id

curl -s -X PATCH \
  "https://api.hookdeploy.dev/v1/incidents/INCIDENT_ID" \
  -H "Authorization: Bearer hd_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "investigating"}'

Body fields:

For external integrations (Zapier, n8n, custom webhooks), the meaningful targets are usually investigating and resolved. Reopening to open is supported but uncommon.

Moving to investigating sets investigating_at (retained afterward). Moving to resolved sets resolved_at / resolved_by.

Replay incident

POST /v1/incidents/:id/replay

Queues a paced replay of all unreplayed failures for the incident.

curl -s -X POST \
  "https://api.hookdeploy.dev/v1/incidents/INCIDENT_ID/replay" \
  -H "Authorization: Bearer hd_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"requests_per_minute": 60}'

Body fields:

Success response:

{
  "data": {
    "replay_batch_id": "44444444-4444-4444-4444-444444444444",
    "queued_count": 42,
    "requests_per_minute": 60
  }
}

Requires Starter or above. Free plans receive 403 / plan_limit.

If the chosen rate would make the batch take longer than 12 hours, the API returns 400 / bad_request with a message asking you to increase the rate or replay a subset.

Error responses

Next steps

• Incidents concept — Correlation, status, and replay behavior
• Incident subscriptions — REST Hook fanout for incident lifecycle events
• Replay API — Replay a single captured request