Every time TagPay dispatches a webhook to a subscription endpoint, a delivery record is created. You can use these records to monitor delivery health, debug failures, and identify events that need replaying.
List delivery attempts Retrieve a paginated list of webhook delivery attempts for your merchant account.
GET https://api.tagpay.ng/v1/merchant/webhook/deliveries
Query parameters Filter deliveries to a specific subscription. Retrieve subscription IDs from List subscriptions . Filter by delivery status. One of pending, success, failed, or retrying.
Filter by event type, e.g. transaction.success.
ISO 8601 date string. Returns deliveries created on or after this timestamp.
ISO 8601 date string. Returns deliveries created on or before this timestamp.
Page number for pagination.
Number of records per page.
Response true when the request succeeded.
Array of delivery records sorted by createdAt descending. Unique delivery ID (UUID).
ID of the subscription this delivery belongs to.
The event type that triggered this delivery, e.g. transaction.success.
Number of delivery attempts made so far.
Maximum allowed attempts. Always 3.
The HTTP status code returned by your endpoint on the last attempt. null if no attempt has completed.
Round-trip response time in milliseconds for the last attempt. null if unavailable.
The response body returned by your endpoint, stored for debugging. null if unavailable.
Error description if the last attempt failed. null on success.
The transaction or event reference that triggered this delivery.
The exact JSON payload that was (or will be) sent to your endpoint.
ISO 8601 timestamp of the next scheduled retry. null if no retry is scheduled.
ISO 8601 timestamp of the successful delivery. null if not yet delivered.
ISO 8601 timestamp when the delivery record was created.
Summary of the associated subscription. Show Subscription summary
Subscription description.
curl --request GET \ --url "https://api.tagpay.ng/v1/merchant/webhook/deliveries?status=failed&page=1&limit=20" \ --header "Authorization: Bearer <token>"
{ "status" : true , "message" : "Deliveries retrieved successfully" , "data" : [ { "id" : "del_f6a7b8c9-d0e1-2345-fabc-678901234567" , "subscriptionId" : "sub_e5f6a7b8-c9d0-1234-efab-567890123456" , "merchantId" : "merch_001" , "eventType" : "transaction.success" , "status" : "failed" , "attempts" : 3 , "maxAttempts" : 3 , "httpStatusCode" : 500 , "responseTimeMs" : 234 , "response" : null , "errorMessage" : "Request failed with status code 500" , "reference" : "TXN-20240401-001" , "payload" : { "event" : "transaction.success" , "data" : { "id" : "a1b2c3d4-e5f6-7890-abcd-ef1234567890" , "reference" : "TXN-20240401-001" , "amount" : 500000 , "status" : "success" } }, "nextRetryAt" : null , "deliveredAt" : null , "createdAt" : "2024-04-01T10:30:10.000Z" , "subscription" : { "id" : "sub_e5f6a7b8-c9d0-1234-efab-567890123456" , "url" : "https://example.com/webhooks/tagpay" , "description" : "Production webhook endpoint" } } ], "metadata" : { "page" : 1 , "limit" : 20 , "total" : 12 , "totalPages" : 1 } }
Get a single delivery Retrieve full details for a specific delivery record, including the complete payload and subscription information.
GET https://api.tagpay.ng/v1/merchant/webhook/delivery/:id
Path parameters The UUID of the delivery record.
Response Returns a single delivery object with all fields described above, plus the full subscription detail including the events array.
curl --request GET \ --url "https://api.tagpay.ng/v1/merchant/webhook/delivery/del_f6a7b8c9-d0e1-2345-fabc-678901234567" \ --header "Authorization: Bearer <token>"
{ "status" : true , "message" : "Delivery retrieved successfully" , "data" : { "id" : "del_f6a7b8c9-d0e1-2345-fabc-678901234567" , "subscriptionId" : "sub_e5f6a7b8-c9d0-1234-efab-567890123456" , "merchantId" : "merch_001" , "eventType" : "transaction.success" , "status" : "failed" , "attempts" : 3 , "maxAttempts" : 3 , "httpStatusCode" : 500 , "responseTimeMs" : 234 , "response" : null , "errorMessage" : "Request failed with status code 500" , "reference" : "TXN-20240401-001" , "payload" : { "event" : "transaction.success" , "data" : { "id" : "a1b2c3d4-e5f6-7890-abcd-ef1234567890" , "reference" : "TXN-20240401-001" , "amount" : 500000 , "status" : "success" } }, "nextRetryAt" : null , "deliveredAt" : null , "createdAt" : "2024-04-01T10:30:10.000Z" , "subscription" : { "id" : "sub_e5f6a7b8-c9d0-1234-efab-567890123456" , "url" : "https://example.com/webhooks/tagpay" , "description" : "Production webhook endpoint" , "events" : [ "transaction.success" , "wallet.credit" ] } } }
Delivery statuses Each delivery record moves through the following statuses:
Status Description pendingThe delivery has been queued and no attempt has been made yet. retryingA previous attempt failed and a retry is scheduled. successYour endpoint returned a 2xx HTTP status code. failedAll retry attempts were exhausted without a 2xx response.
TagPay makes up to 3 delivery attempts per event. After the first failure the system retries after 1 minute, then again after 5 minutes. If all three attempts fail, the delivery status becomes failed and no further retries are attempted automatically. Use the replay endpoint to manually retry. 