Deliveries API

Deliveries represent attempts to send webhooks to destinations.

Endpoints

Method	Path	Description
GET	/api/organizations/{orgId}/deliveries	List deliveries
GET	/api/organizations/{orgId}/deliveries/{id}	Get delivery
POST	/api/organizations/{orgId}/deliveries/{id}/retry	Retry delivery

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
delivered	Successfully delivered
failed	All retry attempts exhausted
retrying	Waiting to retry

List Deliveries

GET /api/organizations/{orgId}/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.webhookrelay.com/api/organizations/org_123/deliveries?status=failed&destinationId=dst_api" \
  -H "Authorization: Bearer YOUR_TOKEN"

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/organizations/{orgId}/deliveries/{id}

Query Parameters

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

Example

curl "https://api.webhookrelay.com/api/organizations/org_123/deliveries/dlv_abc123?includeAttempts=true" \
  -H "Authorization: Bearer YOUR_TOKEN"

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/organizations/{orgId}/deliveries/{id}/retry

INFO

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

Example

curl -X POST https://api.webhookrelay.com/api/organizations/org_123/deliveries/dlv_abc123/retry \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

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

Dead Letter Queue

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

List Dead Letter Items

GET /api/organizations/{orgId}/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.webhookrelay.com/api/organizations/org_123/deliveries/dead-letter \
  -H "Authorization: Bearer YOUR_TOKEN"

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/organizations/{orgId}/deliveries/dead-letter/{id}/requeue

Example

curl -X POST https://api.webhookrelay.com/api/organizations/org_123/deliveries/dead-letter/dlq_abc123/requeue \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

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

Delete Dead Letter Item

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

Example

curl -X DELETE https://api.webhookrelay.com/api/organizations/org_123/deliveries/dead-letter/dlq_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

204 No Content

Delivery Statistics

GET /api/organizations/{orgId}/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"
}