Deliveries API
A delivery represents one attempt to send an event to a webhook endpoint. Use the Deliveries API to monitor delivery status, inspect request and response details, retry failures, and view aggregate statistics.
Delivery status flow
Every delivery starts as pending and transitions based on your endpoint's response.
Queued, awaiting delivery
Your endpoint returned 2xx
| Status | Description |
|---|---|
| pending | The delivery is queued and will be attempted shortly. |
| delivered | Your endpoint responded with a 2xx HTTP status code within the timeout. |
| retrying | A previous attempt failed. XRNotify will retry with exponential backoff (1m, 5m, 30m, 2h, 8h). |
| failed | All retry attempts were exhausted. Use the retry endpoint to attempt again manually. |
/v1/deliveriesList deliveries with optional filters. Results are ordered by creation time, newest first.
Query parameters
| Parameter | Type | Description |
|---|---|---|
webhook_id | string | Filter to a specific webhook |
event_type | string | Filter by event type (e.g. payment.xrp) |
status | string | Filter by status: delivered, pending, retrying, or failed |
since | ISO timestamp | Return deliveries created after this time |
until | ISO timestamp | Return deliveries created before this time |
limit | integer | Results per page. Default 20, max 100 |
cursor | string | Pagination cursor from a previous response |
curl "https://api.xrnotify.io/v1/deliveries?webhook_id=wh_abc&status=failed&since=2024-01-01T00:00:00Z" \ -H "X-XRNotify-Key: xrn_live_xxx"
Response 200 OK
{
"data": [
{
"id": "dlv_xyz789",
"webhook_id": "wh_abc123",
"event_id": "xrpl:89547832:A4B2F1:payment.xrp",
"event_type": "payment.xrp",
"status": "failed",
"attempts": 5,
"last_error": "Connection refused",
"created_at": "2024-01-15T10:23:45Z",
"updated_at": "2024-01-15T18:30:00Z"
}
],
"has_more": false,
"next_cursor": null
}/v1/deliveries/:idRetrieve full details for a single delivery, including the request body sent, response received, and history of all attempts.
Response 200 OK
{
"id": "dlv_xyz789",
"webhook_id": "wh_abc123",
"event_id": "xrpl:89547832:A4B2F1:payment.xrp",
"event_type": "payment.xrp",
"status": "delivered",
"attempts": 2,
"response_status": 200,
"response_time_ms": 143,
"request_body": "{"event_type":"payment.xrp",...}",
"response_body": "OK",
"last_error": null,
"created_at": "2024-01-15T10:23:45Z",
"updated_at": "2024-01-15T10:24:05Z",
"attempt_history": [
{
"attempt": 1,
"status": "failed",
"response_status": 500,
"response_time_ms": 5032,
"error": "Internal Server Error",
"attempted_at": "2024-01-15T10:23:46Z"
},
{
"attempt": 2,
"status": "delivered",
"response_status": 200,
"response_time_ms": 143,
"attempted_at": "2024-01-15T10:24:05Z"
}
]
}/v1/deliveries/:id/retryManually trigger a retry for a failed delivery. The delivery is re-queued as pending and will be attempted shortly.
Note: Retried deliveries count against your plan's monthly delivery quota. Consider using the Replay API for bulk re-delivery of missed events.
Request
curl -X POST \ https://api.xrnotify.io/v1/deliveries/dlv_xyz789/retry \ -H "X-XRNotify-Key: xrn_live_..."
Response 200 OK
{
"delivery_id": "dlv_xyz789",
"status": "pending"
}/v1/deliveries/statsAggregate delivery statistics for your account. Useful for monitoring overall health and building dashboards.
| Parameter | Description |
|---|---|
webhook_id | Optional. Scope stats to a specific webhook. |
period | Time window: 1h, 24h, 7d, 30d. Default: 24h. |
Request
curl "https://api.xrnotify.io/v1/deliveries/stats?period=24h" \ -H "X-XRNotify-Key: xrn_live_..."
Response 200 OK
{
"period": "24h",
"total": 1284,
"delivered": 1271,
"failed": 8,
"pending": 5,
"success_rate": 99.0,
"avg_latency_ms": 187
}