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}/retry`	Retry delivery
POST	`/api/deliveries/bulk-replay`	Bulk replay deliveries

Delivery Object

{
  "id": "dlv_abc123",
  "eventId": "evt_xyz789",
  "destinationId": "dst_api123",
  "routeId": "rte_main456",
  "status": "delivered",
  "attemptCount": 1,
  "maxAttempts": 5,
  "latency": 245,
  "statusCode": 200,
  "requestHeaders": {
    "Content-Type": "application/json",
    "Authorization": "Bearer ***",
    "X-Webhook-ID": "evt_xyz789"
  },
  "responseHeaders": {
    "Content-Type": "application/json",
    "X-Request-ID": "req_abc"
  },
  "responseBody": "{\"received\": true}",
  "error": null,
  "event": {
    "id": "evt_xyz789",
    "sourceId": "src_github"
  },
  "destination": {
    "id": "dst_api123",
    "name": "Production API",
    "url": "https://api.yourapp.com/webhooks"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:01Z",
  "deliveredAt": "2024-01-15T10:30:01Z"
}

Status Values

Status	Description
`pending`	Awaiting delivery
`sent`	Request sent, awaiting response
`delivered`	Successfully delivered (2xx response)
`failed`	All retry attempts exhausted
`retrying`	Waiting to retry
`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
page	number	Page number (default: 1)
pageSize	number	Items per page (default: 20, max: 100)
eventId	string	Filter by event
destinationId	string	Filter by destination
routeId	string	Filter by route
status	string	Filter by status
from	string	Start date (ISO 8601)
to	string	End date (ISO 8601)

Example

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

Response

{
  "data": [
    {
      "id": "dlv_abc123",
      "eventId": "evt_xyz789",
      "destinationId": "dst_api123",
      "status": "failed",
      "attemptCount": 5,
      "maxAttempts": 5,
      "statusCode": 500,
      "error": "Internal Server Error",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 34,
    "page": 1,
    "pageSize": 20
  }
}

Get Delivery

GET /api/deliveries/{id}

Query Parameters

Parameter	Type	Description
includeAttempts	boolean	Include all attempt details (default: false)

Example

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

Response

{
  "id": "dlv_abc123",
  "eventId": "evt_xyz789",
  "destinationId": "dst_api123",
  "status": "delivered",
  "attemptCount": 2,
  "maxAttempts": 5,
  "latency": 180,
  "statusCode": 200,
  "attempts": [
    {
      "attemptNumber": 1,
      "startedAt": "2024-01-15T10:30:00Z",
      "completedAt": "2024-01-15T10:30:01Z",
      "statusCode": 503,
      "error": "Service Unavailable",
      "latency": 5023
    },
    {
      "attemptNumber": 2,
      "startedAt": "2024-01-15T10:30:02Z",
      "completedAt": "2024-01-15T10:30:02Z",
      "statusCode": 200,
      "error": null,
      "latency": 180
    }
  ],
  "requestHeaders": {
    "Content-Type": "application/json"
  },
  "responseHeaders": {
    "Content-Type": "application/json"
  },
  "responseBody": "{\"received\": true}",
  "deliveredAt": "2024-01-15T10:30:02Z"
}

Retry Delivery

Manually retry a failed delivery:

POST /api/deliveries/{id}/retry

Info

This resets the attempt count and queues the delivery for immediate retry.

Example

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

Response

{
  "message": "Delivery queued for retry",
  "deliveryId": "dlv_abc123",
  "status": "pending"
}

Bulk Replay

Replay multiple failed deliveries 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": "Deliveries queued for replay",
  "queued": 3,
  "skipped": 0,
  "errors": []
}

Info

Only deliveries with status failed or circuit_open can be replayed. Deliveries in other states are skipped.

Dead Letter Queue

Failed deliveries are moved to the dead letter queue for manual review.

List Dead Letter Items

GET /api/deliveries/dead-letter

Query Parameters

Parameter	Type	Description
page	number	Page number
pageSize	number	Items per page
destinationId	string	Filter by destination
from	string	Start date
to	string	End date

Example

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

Response

{
  "data": [
    {
      "id": "dlq_abc123",
      "deliveryId": "dlv_xyz789",
      "eventId": "evt_main123",
      "destinationId": "dst_api",
      "error": "Connection timeout after 30000ms",
      "attemptCount": 5,
      "failedAt": "2024-01-15T10:35:00Z",
      "event": {
        "id": "evt_main123",
        "receivedAt": "2024-01-15T10:30:00Z"
      },
      "destination": {
        "id": "dst_api",
        "name": "Production API"
      }
    }
  ],
  "pagination": {
    "total": 12,
    "page": 1,
    "pageSize": 20
  }
}

Requeue Dead Letter Item

POST /api/deliveries/dead-letter/{id}/requeue

Example

curl -X POST https://api.hookbase.app/api/deliveries/dead-letter/dlq_abc123/requeue \
  -H "Authorization: Bearer whr_your_api_key"

Response

{
  "message": "Item requeued for delivery",
  "deliveryId": "dlv_new456"
}

Delete Dead Letter Item

DELETE /api/deliveries/dead-letter/{id}

Example

curl -X DELETE https://api.hookbase.app/api/deliveries/dead-letter/dlq_abc123 \
  -H "Authorization: Bearer whr_your_api_key"

Response

204 No Content

Delivery Statistics

GET /api/deliveries/stats

Query Parameters

Parameter	Type	Description
period	string	`1h`, `24h`, `7d`, `30d`
destinationId	string	Filter by destination

Response

{
  "total": 5230,
  "delivered": 5152,
  "failed": 78,
  "pending": 0,
  "successRate": 98.5,
  "avgLatency": 245,
  "p50Latency": 180,
  "p95Latency": 450,
  "p99Latency": 890,
  "period": "24h"
}

Error Responses

404 Not Found

Delivery not found:

{
  "error": "Not Found",
  "message": "Delivery with ID dlv_xyz not found",
  "code": "RESOURCE_NOT_FOUND"
}

409 Conflict

Cannot retry delivery:

{
  "error": "Conflict",
  "message": "Delivery is already pending or delivered",
  "code": "INVALID_STATE"
}

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}/retry`	Retry delivery
POST	`/api/deliveries/bulk-replay`	Bulk replay deliveries

Delivery Object

{
  "id": "dlv_abc123",
  "eventId": "evt_xyz789",
  "destinationId": "dst_api123",
  "routeId": "rte_main456",
  "status": "delivered",
  "attemptCount": 1,
  "maxAttempts": 5,
  "latency": 245,
  "statusCode": 200,
  "requestHeaders": {
    "Content-Type": "application/json",
    "Authorization": "Bearer ***",
    "X-Webhook-ID": "evt_xyz789"
  },
  "responseHeaders": {
    "Content-Type": "application/json",
    "X-Request-ID": "req_abc"
  },
  "responseBody": "{\"received\": true}",
  "error": null,
  "event": {
    "id": "evt_xyz789",
    "sourceId": "src_github"
  },
  "destination": {
    "id": "dst_api123",
    "name": "Production API",
    "url": "https://api.yourapp.com/webhooks"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:01Z",
  "deliveredAt": "2024-01-15T10:30:01Z"
}

Status Values

Status	Description
`pending`	Awaiting delivery
`sent`	Request sent, awaiting response
`delivered`	Successfully delivered (2xx response)
`failed`	All retry attempts exhausted
`retrying`	Waiting to retry
`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
page	number	Page number (default: 1)
pageSize	number	Items per page (default: 20, max: 100)
eventId	string	Filter by event
destinationId	string	Filter by destination
routeId	string	Filter by route
status	string	Filter by status
from	string	Start date (ISO 8601)
to	string	End date (ISO 8601)

Example

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

Response

{
  "data": [
    {
      "id": "dlv_abc123",
      "eventId": "evt_xyz789",
      "destinationId": "dst_api123",
      "status": "failed",
      "attemptCount": 5,
      "maxAttempts": 5,
      "statusCode": 500,
      "error": "Internal Server Error",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 34,
    "page": 1,
    "pageSize": 20
  }
}

Get Delivery

GET /api/deliveries/{id}

Query Parameters

Parameter	Type	Description
includeAttempts	boolean	Include all attempt details (default: false)

Example

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

Response

{
  "id": "dlv_abc123",
  "eventId": "evt_xyz789",
  "destinationId": "dst_api123",
  "status": "delivered",
  "attemptCount": 2,
  "maxAttempts": 5,
  "latency": 180,
  "statusCode": 200,
  "attempts": [
    {
      "attemptNumber": 1,
      "startedAt": "2024-01-15T10:30:00Z",
      "completedAt": "2024-01-15T10:30:01Z",
      "statusCode": 503,
      "error": "Service Unavailable",
      "latency": 5023
    },
    {
      "attemptNumber": 2,
      "startedAt": "2024-01-15T10:30:02Z",
      "completedAt": "2024-01-15T10:30:02Z",
      "statusCode": 200,
      "error": null,
      "latency": 180
    }
  ],
  "requestHeaders": {
    "Content-Type": "application/json"
  },
  "responseHeaders": {
    "Content-Type": "application/json"
  },
  "responseBody": "{\"received\": true}",
  "deliveredAt": "2024-01-15T10:30:02Z"
}

Retry Delivery

Manually retry a failed delivery:

POST /api/deliveries/{id}/retry

Info

This resets the attempt count and queues the delivery for immediate retry.

Example

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

Response

{
  "message": "Delivery queued for retry",
  "deliveryId": "dlv_abc123",
  "status": "pending"
}

Bulk Replay

Replay multiple failed deliveries 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": "Deliveries queued for replay",
  "queued": 3,
  "skipped": 0,
  "errors": []
}

Info

Only deliveries with status failed or circuit_open can be replayed. Deliveries in other states are skipped.

Dead Letter Queue

Failed deliveries are moved to the dead letter queue for manual review.

List Dead Letter Items

GET /api/deliveries/dead-letter

Query Parameters

Parameter	Type	Description
page	number	Page number
pageSize	number	Items per page
destinationId	string	Filter by destination
from	string	Start date
to	string	End date

Example

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

Response

{
  "data": [
    {
      "id": "dlq_abc123",
      "deliveryId": "dlv_xyz789",
      "eventId": "evt_main123",
      "destinationId": "dst_api",
      "error": "Connection timeout after 30000ms",
      "attemptCount": 5,
      "failedAt": "2024-01-15T10:35:00Z",
      "event": {
        "id": "evt_main123",
        "receivedAt": "2024-01-15T10:30:00Z"
      },
      "destination": {
        "id": "dst_api",
        "name": "Production API"
      }
    }
  ],
  "pagination": {
    "total": 12,
    "page": 1,
    "pageSize": 20
  }
}

Requeue Dead Letter Item

POST /api/deliveries/dead-letter/{id}/requeue

Example

curl -X POST https://api.hookbase.app/api/deliveries/dead-letter/dlq_abc123/requeue \
  -H "Authorization: Bearer whr_your_api_key"

Response

{
  "message": "Item requeued for delivery",
  "deliveryId": "dlv_new456"
}

Delete Dead Letter Item

DELETE /api/deliveries/dead-letter/{id}

Example

curl -X DELETE https://api.hookbase.app/api/deliveries/dead-letter/dlq_abc123 \
  -H "Authorization: Bearer whr_your_api_key"

Response

204 No Content

Delivery Statistics

GET /api/deliveries/stats

Query Parameters

Parameter	Type	Description
period	string	`1h`, `24h`, `7d`, `30d`
destinationId	string	Filter by destination

Response

{
  "total": 5230,
  "delivered": 5152,
  "failed": 78,
  "pending": 0,
  "successRate": 98.5,
  "avgLatency": 245,
  "p50Latency": 180,
  "p95Latency": 450,
  "p99Latency": 890,
  "period": "24h"
}

Error Responses

404 Not Found

Delivery not found:

{
  "error": "Not Found",
  "message": "Delivery with ID dlv_xyz not found",
  "code": "RESOURCE_NOT_FOUND"
}

409 Conflict

Cannot retry delivery:

{
  "error": "Conflict",
  "message": "Delivery is already pending or delivered",
  "code": "INVALID_STATE"
}