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

json

{
  "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

http

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

curlJavaScriptPython

bash

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

javascript

const response = await fetch('https://api.hookbase.app/api/deliveries?status=failed&destinationId=dst_api', {
  headers: {
    'Authorization': 'Bearer whr_your_api_key'
  }
});
const { data } = await response.json();

python

import requests

response = requests.get(
  'https://api.hookbase.app/api/deliveries?status=failed&destinationId=dst_api',
  headers={'Authorization': 'Bearer whr_your_api_key'}
)
data = response.json()['data']

Response

json

{
  "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

http

GET /api/deliveries/{id}

Query Parameters

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

Example

curlJavaScriptPython

bash

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

javascript

const response = await fetch('https://api.hookbase.app/api/deliveries/dlv_abc123?includeAttempts=true', {
  headers: {
    'Authorization': 'Bearer whr_your_api_key'
  }
});
const data = await response.json();

python

import requests

response = requests.get(
  'https://api.hookbase.app/api/deliveries/dlv_abc123?includeAttempts=true',
  headers={'Authorization': 'Bearer whr_your_api_key'}
)
data = response.json()

Response

json

{
  "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:

http

POST /api/deliveries/{id}/retry

INFO

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

Example

curlJavaScriptPython

bash

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

javascript

const response = await fetch('https://api.hookbase.app/api/deliveries/dlv_abc123/retry', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer whr_your_api_key'
  }
});
const data = await response.json();

python

import requests

response = requests.post(
  'https://api.hookbase.app/api/deliveries/dlv_abc123/retry',
  headers={'Authorization': 'Bearer whr_your_api_key'}
)
data = response.json()

Response

json

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

Bulk Replay

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

http

POST /api/deliveries/bulk-replay

Request Body

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

Example

curlJavaScriptPython

bash

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"]
  }'

javascript

const response = await fetch('https://api.hookbase.app/api/deliveries/bulk-replay', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer whr_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    deliveryIds: ['dlv_abc123', 'dlv_def456', 'dlv_ghi789']
  })
});
const data = await response.json();

python

import requests

response = requests.post(
  'https://api.hookbase.app/api/deliveries/bulk-replay',
  headers={'Authorization': 'Bearer whr_your_api_key'},
  json={'deliveryIds': ['dlv_abc123', 'dlv_def456', 'dlv_ghi789']}
)
data = response.json()

Response

json

{
  "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

http

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

curlJavaScriptPython

bash

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

javascript

const response = await fetch('https://api.hookbase.app/api/deliveries/dead-letter', {
  headers: {
    'Authorization': 'Bearer whr_your_api_key'
  }
});
const { data } = await response.json();

python

import requests

response = requests.get(
  'https://api.hookbase.app/api/deliveries/dead-letter',
  headers={'Authorization': 'Bearer whr_your_api_key'}
)
data = response.json()['data']

Response

json

{
  "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

http

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

Example

curlJavaScriptPython

bash

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

javascript

const response = await fetch('https://api.hookbase.app/api/deliveries/dead-letter/dlq_abc123/requeue', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer whr_your_api_key'
  }
});
const data = await response.json();

python

import requests

response = requests.post(
  'https://api.hookbase.app/api/deliveries/dead-letter/dlq_abc123/requeue',
  headers={'Authorization': 'Bearer whr_your_api_key'}
)
data = response.json()

Response

json

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

Delete Dead Letter Item

http

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

Example

curlJavaScriptPython

bash

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

javascript

const response = await fetch('https://api.hookbase.app/api/deliveries/dead-letter/dlq_abc123', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer whr_your_api_key'
  }
});

python

import requests

response = requests.delete(
  'https://api.hookbase.app/api/deliveries/dead-letter/dlq_abc123',
  headers={'Authorization': 'Bearer whr_your_api_key'}
)

Response

204 No Content

Delivery Statistics

http

GET /api/deliveries/stats

Query Parameters

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

Response

json

{
  "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:

json

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

409 Conflict

Cannot retry delivery:

json

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

Deliveries API ​

Endpoints ​

Delivery Object ​

Status Values ​

List Deliveries ​

Query Parameters ​

Example ​

Response ​

Get Delivery ​

Query Parameters ​

Example ​

Response ​

Retry Delivery ​

Example ​

Response ​

Bulk Replay ​

Request Body ​

Example ​

Response ​

Dead Letter Queue ​

List Dead Letter Items ​

Query Parameters ​

Example ​

Response ​

Requeue Dead Letter Item ​

Example ​

Response ​

Delete Dead Letter Item ​

Example ​

Response ​

Delivery Statistics ​

Query Parameters ​

Response ​

Error Responses ​

404 Not Found ​

409 Conflict ​

Deliveries API

Endpoints

Delivery Object

Status Values

List Deliveries

Query Parameters

Example

Response

Get Delivery

Query Parameters

Example

Response

Retry Delivery

Example

Response

Bulk Replay

Request Body

Example

Response

Dead Letter Queue

List Dead Letter Items

Query Parameters

Example

Response

Requeue Dead Letter Item

Example

Response

Delete Dead Letter Item

Example

Response

Delivery Statistics

Query Parameters

Response

Error Responses

404 Not Found

409 Conflict