Skip to main content

​
Overview

Returns a paginated list of webhook delivery attempts for your partner account. Use this to monitor delivery health, inspect failed deliveries, and debug issues.

​
Endpoint

GET /partners/webhooks/deliveries

​
Authentication

Requires a valid API Key with the partner_webhooks_manage permission.

​
Query Parameters

ParameterTypeRequiredDescription
pageintegerNoPage number. Default: 1.
limitintegerNoResults per page. Default: 20. Max: 100.
subscriptionIdUUIDNoFilter by a specific subscription ID.
statusstringNoFilter by delivery status: PENDING, DELIVERED, or FAILED.

​
Example Requests

​
List all deliveries

curl -X GET "https://apiv3.thecleanlife.dev/v1/partners/webhooks/deliveries" \
  -H "x-api-key: YOUR_API_KEY"

​
List failed deliveries for a specific subscription

curl -X GET "https://apiv3.thecleanlife.dev/v1/partners/webhooks/deliveries?subscriptionId=gggggggg-0000-0000-0000-000000000001&status=FAILED" \
  -H "x-api-key: YOUR_API_KEY"

​
Success Response

HTTP Status: 200 OK 
{
  "success": true,
  "data": [
    {
      "id": "iiiiiiii-0000-0000-0000-000000000001",
      "subscriptionId": "gggggggg-0000-0000-0000-000000000001",
      "event": "booking.created",
      "status": "DELIVERED",
      "attemptCount": 1,
      "statusCode": 200,
      "error": null,
      "nextRetryAt": null,
      "deliveredAt": "2026-06-15T10:01:05+03:00",
      "createdAt": "2026-06-15T10:00:00+03:00"
    },
    {
      "id": "jjjjjjjj-0000-0000-0000-000000000002",
      "subscriptionId": "gggggggg-0000-0000-0000-000000000001",
      "event": "booking.cancelled",
      "status": "FAILED",
      "attemptCount": 4,
      "statusCode": 503,
      "error": "Webhook endpoint returned HTTP 503",
      "nextRetryAt": null,
      "deliveredAt": null,
      "createdAt": "2026-06-15T09:00:00+03:00"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 2,
    "totalPages": 1
  }
}

​
Response Field Reference

FieldTypeDescription
idUUIDUnique delivery identifier. Use this for retry requests.
subscriptionIdUUIDThe subscription this delivery belongs to.
eventstringThe event type that was delivered.
statusstringCurrent delivery status: PENDING, DELIVERED, or FAILED.
attemptCountintegerNumber of delivery attempts made so far.
statusCodeinteger / nullHTTP status code returned by your endpoint on the last attempt. null if no response received (network error).
errorstring / nullError message from the last failed attempt. null on success.
nextRetryAtdatetime / nullWhen the next automatic retry is scheduled. null if delivered or permanently failed.
deliveredAtdatetime / nullWhen the delivery was successfully received by your endpoint. null if not yet delivered.
createdAtdatetimeWhen the delivery record was created.

​
Delivery Statuses

StatusMeaning
PENDINGAwaiting dispatch, currently being dispatched, or scheduled for retry.
DELIVEREDYour endpoint returned a 2xx response.
FAILEDAll retry attempts exhausted (4 attempts total: 1 initial + 3 retries). Manual retry available.

​
Error Responses

HTTP StatusCodeDescription
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENMissing partner_webhooks_manage permission

​
Notes

  • PENDING deliveries include both those waiting for first dispatch and those scheduled for retry.
  • Delivery records are not deleted and serve as a permanent audit log.
  • Use the id from a FAILED delivery to trigger a manual retry via POST /partners/webhooks/deliveries/:id/retry.
  • POST /partners/webhooks/deliveries/:id/retry — Manually retry a failed delivery