Delivery Clusters API
Hookbase groups failed deliveries that share a failure fingerprint (same route, destination, response status, and error signature) into clusters, so you can triage a recurring failure once instead of delivery-by-delivery.
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /api/delivery-clusters | List recent failure clusters |
| GET | /api/delivery-clusters/{fingerprint}/events | List the events in a cluster |
| POST | /api/delivery-clusters/{fingerprint}/replay-all | Replay every delivery in a cluster |
Cluster Object
{
"fingerprint": "a1b2c3d4",
"count": 128,
"affectedEventCount": 128,
"firstSeen": "2024-01-15T08:00:00Z",
"lastSeen": "2024-01-15T10:30:00Z",
"routeId": "rte_main456",
"routeName": "GitHub to Production",
"destinationId": "dst_api123",
"destinationName": "Production API",
"responseStatus": 500,
"errorMessageExcerpt": "Internal Server Error",
"rcaCategory": "destination_5xx",
"sampleDeliveryId": "dlv_abc123",
"sampleEventId": "evt_xyz789"
}List Clusters
GET /api/delivery-clustersQuery Parameters
| Parameter | Type | Description |
|---|---|---|
| sinceHours | number | Look-back window in hours (default: 24, max: 720) |
| limit | number | Max clusters to return (default: 50, max: 200) |
Example
curl "https://api.hookbase.app/api/delivery-clusters?sinceHours=24&limit=50" \
-H "Authorization: Bearer whr_your_api_key"Response
{
"clusters": [
{
"fingerprint": "a1b2c3d4",
"count": 128,
"destinationName": "Production API",
"responseStatus": 500,
"errorMessageExcerpt": "Internal Server Error",
"firstSeen": "2024-01-15T08:00:00Z",
"lastSeen": "2024-01-15T10:30:00Z"
}
],
"since": "2024-01-14T10:30:00Z",
"sinceHours": 24
}List Cluster Events
Return the events whose deliveries belong to a cluster.
GET /api/delivery-clusters/{fingerprint}/eventsQuery Parameters
| Parameter | Type | Description |
|---|---|---|
| limit | number | Max events to return (default: 500, max: 5000) |
Replay a Cluster
Replay every failed delivery in a cluster in one call. Optionally override the destination, apply a one-off transform, or add headers.
POST /api/delivery-clusters/{fingerprint}/replay-allRequest Body (optional)
| Field | Type | Description |
|---|---|---|
| destinationOverride | string | Send all replays to a different destination ID |
| transformOverride | object | { code, type?, inputFormat?, outputFormat? } (code max 64KB) |
| headersOverride | object | Extra request headers (max 50) |
| persistTransform | boolean | Save transformOverride to the route (requires transformOverride) |
| limit | number | Cap the number of deliveries replayed |
Example
curl -X POST https://api.hookbase.app/api/delivery-clusters/a1b2c3d4/replay-all \
-H "Authorization: Bearer whr_your_api_key" \
-H "Content-Type: application/json" \
-d '{ "limit": 100 }'Info
Clusters are a read/triage view over failed deliveries — see the Deliveries API to inspect or replay an individual delivery.