Webhook Service

Manages webhook delivery status and retry logic for asynchronous jobs.

---

Endpoints

---

Get Webhook Delivery Status

GET /webhooks/delivery/status/:requestId

Retrieve the delivery status and details for a specific webhook request.

Path Parameters

Parameter	Type	Required	Description	Example
requestId	string	Yes	The request ID to check status for	"req-123e4567-e89b-12d3-a456-426614174000"

Success Response

Returns delivery status and details.

{
  "requestId": "req-123e4567-e89b-12d3-a456-426614174000",
  "deliveryId": "del-789e4567-e89b-12d3-a456-426614174000",
  "status": "delivered",
  "attemptCount": 2,
  "maxRetries": 5,
  "lastError": null,
  "lastAttemptAt": "2025-11-20T12:34:56.789Z",
  "successAt": "2025-11-20T12:35:10.123Z",
  "httpStatus": 200,
  "webhookUrl": "https://client.example.com/webhook",
  "createdAt": "2025-11-20T12:34:00.000Z",
  "updatedAt": "2025-11-20T12:35:10.123Z"
}

Error Responses

• 404 Not Found: No webhook delivery found for the given request ID

---

Get Failed Webhook Deliveries

GET /webhooks/delivery/failed

Retrieve webhook deliveries that failed after maximum retries.

Query Parameters

Parameter	Type	Required	Description	Example
limit	number	No	Maximum number of failed deliveries to return (default: 50, max: 200)	50

Success Response

Returns a list of failed deliveries.

{
  "count": 2,
  "limit": 50,
  "deliveries": [
    {
      "deliveryId": "del-789e4567-e89b-12d3-a456-426614174000",
      "requestId": "req-123e4567-e89b-12d3-a456-426614174000",
      "status": "failed",
      "attemptCount": 5,
      "lastError": "Timeout",
      "lastAttemptAt": "2025-11-20T12:36:00.000Z",
      "webhookUrl": "https://client.example.com/webhook",
      "createdAt": "2025-11-20T12:34:00.000Z",
      "updatedAt": "2025-11-20T12:36:00.000Z"
    }
    // ...more deliveries
  ]
}

---

Get Pending Webhook Retries

GET /webhooks/delivery/pending-retries

Retrieve webhook deliveries that are pending retry.

Success Response

Returns a list of pending retry deliveries.

{
  "count": 1,
  "deliveries": [
    {
      "deliveryId": "del-789e4567-e89b-12d3-a456-426614174000",
      "requestId": "req-123e4567-e89b-12d3-a456-426614174000",
      "status": "pending_retry",
      "attemptCount": 3,
      "maxRetries": 5,
      "lastError": "Connection refused",
      "webhookUrl": "https://client.example.com/webhook",
      "createdAt": "2025-11-20T12:34:00.000Z"
    }
    // ...more deliveries
  ]
}

---

Error Format

All error responses follow this format:

{
  "statusCode": "ERROR_CODE",
  "error": ["Description of the error"],
  "requestId": "72e32108-6260-45e9-bb12-325fe3b61e42",
  "path": "endpoint path",
  "timestamp": "2025-11-19T16:32:57.915Z"
}

---

Field Descriptions

Field	Type	Description
deliveryId	string	Unique identifier for the webhook delivery
requestId	string	Request ID associated with the webhook delivery
status	enum	Delivery status (delivered, failed, pending_retry, not_found)
attemptCount	number	Number of delivery attempts
maxRetries	number	Maximum number of retry attempts allowed
lastError	string	Error message from last attempt (if any)
lastAttemptAt	string	ISO8601 timestamp of last delivery attempt
successAt	string	ISO8601 timestamp of successful delivery (if delivered)
httpStatus	number	HTTP status code from last attempt
webhookUrl	string	Target webhook URL
createdAt	string	ISO8601 timestamp of delivery creation
updatedAt	string	ISO8601 timestamp of last update

---

For enum values, see WebhookDeliveryStatus definition.