Deliveries API

Deliveries represent attempts to send webhooks to destinations.

Endpoints

Method	Path	Description
GET	`/api/deliveries`	List deliveries
GET	`/api/deliveries/{id}`	Get delivery
POST	`/api/deliveries/{id}/replay`	Replay a delivery
POST	`/api/deliveries/{id}/analyze`	AI failure root-cause analysis (Pro+)
POST	`/api/deliveries/bulk-replay`	Replay deliveries by ID (up to 100)
POST	`/api/deliveries/bulk-replay-events`	Replay failed deliveries for events or a time window

Info

There is no dead-letter queue for inbound deliveries — failed deliveries are retried automatically and can be replayed manually. A dead-letter queue exists only for outbound webhooks (see the Webhooks API).

Delivery Object

{
  "id": "dlv_abc123",
  "organizationId": "org_123",
  "eventId": "evt_xyz789",
  "routeId": "rte_main456",
  "destinationId": "dst_api123",
  "status": "delivered",
  "attemptCount": 1,
  "maxAttempts": 5,
  "nextRetryAt": null,
  "responseStatus": 200,
  "responseHeaders": {
    "Content-Type": "application/json",
    "X-Request-ID": "req_abc"
  },
  "responseBody": "{\"received\": true}",
  "latencyMs": 245,
  "errorMessage": null,
  "deliveredAt": "2024-01-15T10:30:01Z",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:01Z",
  "destinationName": "Production API",
  "eventType": "push"
}

Status Values

Status	Description
`pending`	Awaiting delivery (or waiting to retry)
`delivered`	Successfully delivered (2xx response)
`failed`	All retry attempts exhausted
`circuit_open`	Delivery blocked by open circuit breaker
`schema_failed`	Payload failed schema validation
`partial`	Delivered to some destinations but not all

List Deliveries

GET /api/deliveries

Query Parameters

Parameter	Type	Description
limit	number	Max items to return (default: 50)
offset	number	Number of items to skip (default: 0)
status	string	Filter by status

Example

curl "https://api.hookbase.app/api/deliveries?status=failed&limit=20" \
  -H "Authorization: Bearer whr_your_api_key"

Response

{
  "deliveries": [
    {
      "id": "dlv_abc123",
      "eventId": "evt_xyz789",
      "destinationId": "dst_api123",
      "status": "failed",
      "attemptCount": 5,
      "maxAttempts": 5,
      "responseStatus": 500,
      "latencyMs": 812,
      "errorMessage": "Internal Server Error",
      "destinationName": "Production API",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "limit": 20,
  "offset": 0
}

Get Delivery

GET /api/deliveries/{id}

Example

curl "https://api.hookbase.app/api/deliveries/dlv_abc123" \
  -H "Authorization: Bearer whr_your_api_key"

Response

{
  "delivery": {
    "id": "dlv_abc123",
    "organizationId": "org_123",
    "eventId": "evt_xyz789",
    "routeId": "rte_main456",
    "destinationId": "dst_api123",
    "status": "delivered",
    "attemptCount": 2,
    "maxAttempts": 5,
    "nextRetryAt": null,
    "responseStatus": 200,
    "responseHeaders": {
      "Content-Type": "application/json"
    },
    "responseBody": "{\"received\": true}",
    "latencyMs": 180,
    "errorMessage": null,
    "deliveredAt": "2024-01-15T10:30:02Z",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:02Z",
    "destinationName": "Production API",
    "destinationUrl": "https://api.yourapp.com/webhooks"
  }
}

Replay a Delivery

Create a fresh delivery from an existing one and queue it immediately:

POST /api/deliveries/{id}/replay

Request Body (optional)

Field	Type	Description
destinationOverride	string	Send to a different destination ID
transformOverride	object	`{ code, type?, inputFormat?, outputFormat? }` — apply a one-off transform
headersOverride	object	Extra request headers (max 50)
persistTransform	boolean	Save `transformOverride` to the route (requires `transformOverride`)

Example

curl -X POST https://api.hookbase.app/api/deliveries/dlv_abc123/replay \
  -H "Authorization: Bearer whr_your_api_key"

Response

{
  "deliveryId": "dlv_new456",
  "message": "Replay queued"
}

Info

Replay creates a new delivery record rather than mutating the original. Events processed in transient mode (payload not stored) cannot be replayed.

Bulk Replay

Replay multiple deliveries by ID in a single request (up to 100).

POST /api/deliveries/bulk-replay

Request Body

Field	Type	Required	Description
deliveryIds	string[]	Yes	Array of delivery IDs to replay (max 100)

Example

curl -X POST https://api.hookbase.app/api/deliveries/bulk-replay \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryIds": ["dlv_abc123", "dlv_def456", "dlv_ghi789"]
  }'

Response

{
  "message": "3 deliveries queued for replay",
  "queued": 3,
  "skipped": 0,
  "results": [
    { "originalId": "dlv_abc123", "newId": "dlv_new001", "status": "queued" }
  ]
}

Info

Deliveries whose event payload is no longer stored (transient events) are skipped and reported in results with status: "skipped".

Bulk Replay by Event

Replay failed deliveries for a set of events, or for every failed event in a time window. Pass either eventIds or a since/until window — not both.

POST /api/deliveries/bulk-replay-events

Request Body

Field	Type	Description
eventIds	string[]	Explicit list of event IDs
since	string	Window start (ISO 8601) — used when `eventIds` is omitted
until	string	Window end (ISO 8601)
destinationOverride	string	Send all replays to a different destination ID
transformOverride	object	`{ code, type?, inputFormat?, outputFormat? }`
headersOverride	object	Extra request headers
persistTransform	boolean	Save `transformOverride` to the route

Example

curl -X POST https://api.hookbase.app/api/deliveries/bulk-replay-events \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "since": "2024-01-15T00:00:00Z",
    "until": "2024-01-15T23:59:59Z"
  }'

Failure Analysis

Run AI-assisted root-cause analysis on a failed delivery (Pro plan and above).

POST /api/deliveries/{id}/analyze

Request Body (optional)

Field	Type	Description
force	boolean	Re-run analysis even if a cached result exists

Error Responses

404 Not Found

{
  "error": "Delivery not found"
}

400 Bad Request

Returned by bulk replay when deliveryIds is missing, empty, or exceeds 100.

{
  "error": "deliveryIds array is required"
}

Deliveries API

Deliveries represent attempts to send webhooks to destinations.

Endpoints

Method	Path	Description
GET	`/api/deliveries`	List deliveries
GET	`/api/deliveries/{id}`	Get delivery
POST	`/api/deliveries/{id}/replay`	Replay a delivery
POST	`/api/deliveries/{id}/analyze`	AI failure root-cause analysis (Pro+)
POST	`/api/deliveries/bulk-replay`	Replay deliveries by ID (up to 100)
POST	`/api/deliveries/bulk-replay-events`	Replay failed deliveries for events or a time window

Info

Delivery Object

{
  "id": "dlv_abc123",
  "organizationId": "org_123",
  "eventId": "evt_xyz789",
  "routeId": "rte_main456",
  "destinationId": "dst_api123",
  "status": "delivered",
  "attemptCount": 1,
  "maxAttempts": 5,
  "nextRetryAt": null,
  "responseStatus": 200,
  "responseHeaders": {
    "Content-Type": "application/json",
    "X-Request-ID": "req_abc"
  },
  "responseBody": "{\"received\": true}",
  "latencyMs": 245,
  "errorMessage": null,
  "deliveredAt": "2024-01-15T10:30:01Z",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:01Z",
  "destinationName": "Production API",
  "eventType": "push"
}

Status Values

Status	Description
`pending`	Awaiting delivery (or waiting to retry)
`delivered`	Successfully delivered (2xx response)
`failed`	All retry attempts exhausted
`circuit_open`	Delivery blocked by open circuit breaker
`schema_failed`	Payload failed schema validation
`partial`	Delivered to some destinations but not all

List Deliveries

GET /api/deliveries

Query Parameters

Parameter	Type	Description
limit	number	Max items to return (default: 50)
offset	number	Number of items to skip (default: 0)
status	string	Filter by status

Example

curl "https://api.hookbase.app/api/deliveries?status=failed&limit=20" \
  -H "Authorization: Bearer whr_your_api_key"

Response

{
  "deliveries": [
    {
      "id": "dlv_abc123",
      "eventId": "evt_xyz789",
      "destinationId": "dst_api123",
      "status": "failed",
      "attemptCount": 5,
      "maxAttempts": 5,
      "responseStatus": 500,
      "latencyMs": 812,
      "errorMessage": "Internal Server Error",
      "destinationName": "Production API",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "limit": 20,
  "offset": 0
}

Get Delivery

GET /api/deliveries/{id}

Example

curl "https://api.hookbase.app/api/deliveries/dlv_abc123" \
  -H "Authorization: Bearer whr_your_api_key"

Response

{
  "delivery": {
    "id": "dlv_abc123",
    "organizationId": "org_123",
    "eventId": "evt_xyz789",
    "routeId": "rte_main456",
    "destinationId": "dst_api123",
    "status": "delivered",
    "attemptCount": 2,
    "maxAttempts": 5,
    "nextRetryAt": null,
    "responseStatus": 200,
    "responseHeaders": {
      "Content-Type": "application/json"
    },
    "responseBody": "{\"received\": true}",
    "latencyMs": 180,
    "errorMessage": null,
    "deliveredAt": "2024-01-15T10:30:02Z",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:02Z",
    "destinationName": "Production API",
    "destinationUrl": "https://api.yourapp.com/webhooks"
  }
}

Replay a Delivery

Create a fresh delivery from an existing one and queue it immediately:

POST /api/deliveries/{id}/replay

Request Body (optional)

Field	Type	Description
destinationOverride	string	Send to a different destination ID
transformOverride	object	`{ code, type?, inputFormat?, outputFormat? }` — apply a one-off transform
headersOverride	object	Extra request headers (max 50)
persistTransform	boolean	Save `transformOverride` to the route (requires `transformOverride`)

Example

curl -X POST https://api.hookbase.app/api/deliveries/dlv_abc123/replay \
  -H "Authorization: Bearer whr_your_api_key"

Response

{
  "deliveryId": "dlv_new456",
  "message": "Replay queued"
}

Info

Replay creates a new delivery record rather than mutating the original. Events processed in transient mode (payload not stored) cannot be replayed.

Bulk Replay

Replay multiple deliveries by ID in a single request (up to 100).

POST /api/deliveries/bulk-replay

Request Body

Field	Type	Required	Description
deliveryIds	string[]	Yes	Array of delivery IDs to replay (max 100)

Example

curl -X POST https://api.hookbase.app/api/deliveries/bulk-replay \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryIds": ["dlv_abc123", "dlv_def456", "dlv_ghi789"]
  }'

Response

{
  "message": "3 deliveries queued for replay",
  "queued": 3,
  "skipped": 0,
  "results": [
    { "originalId": "dlv_abc123", "newId": "dlv_new001", "status": "queued" }
  ]
}

Info

Deliveries whose event payload is no longer stored (transient events) are skipped and reported in results with status: "skipped".

Bulk Replay by Event

Replay failed deliveries for a set of events, or for every failed event in a time window. Pass either eventIds or a since/until window — not both.

POST /api/deliveries/bulk-replay-events

Request Body

Field	Type	Description
eventIds	string[]	Explicit list of event IDs
since	string	Window start (ISO 8601) — used when `eventIds` is omitted
until	string	Window end (ISO 8601)
destinationOverride	string	Send all replays to a different destination ID
transformOverride	object	`{ code, type?, inputFormat?, outputFormat? }`
headersOverride	object	Extra request headers
persistTransform	boolean	Save `transformOverride` to the route

Example

curl -X POST https://api.hookbase.app/api/deliveries/bulk-replay-events \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "since": "2024-01-15T00:00:00Z",
    "until": "2024-01-15T23:59:59Z"
  }'

Failure Analysis

Run AI-assisted root-cause analysis on a failed delivery (Pro plan and above).

POST /api/deliveries/{id}/analyze

Request Body (optional)

Field	Type	Description
force	boolean	Re-run analysis even if a cached result exists

Error Responses

404 Not Found

{
  "error": "Delivery not found"
}

400 Bad Request

Returned by bulk replay when deliveryIds is missing, empty, or exceeds 100.

{
  "error": "deliveryIds array is required"
}