Delivery History

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

string

Filter deliveries to a specific subscription. Retrieve subscription IDs from List subscriptions.

string

Filter by delivery status. One of pending, success, failed, or retrying.

string

Filter by event type, e.g. transaction.success.

string

ISO 8601 date string. Returns deliveries created on or after this timestamp.

string

ISO 8601 date string. Returns deliveries created on or before this timestamp.

number

default:"1"

Page number for pagination.

number

default:"20"

Number of records per page.

Response

boolean

true when the request succeeded.

object[]

Array of delivery records sorted by createdAt descending.

Show Delivery object

string

Unique delivery ID (UUID).

string

ID of the subscription this delivery belongs to.

string

Your merchant ID.

string

The event type that triggered this delivery, e.g. transaction.success.

string

Current delivery status. See Delivery statuses.

number

Number of delivery attempts made so far.

number

Maximum allowed attempts. Always 3.

number

The HTTP status code returned by your endpoint on the last attempt. null if no attempt has completed.

number

Round-trip response time in milliseconds for the last attempt. null if unavailable.

object

The response body returned by your endpoint, stored for debugging. null if unavailable.

string

Error description if the last attempt failed. null on success.

string

The transaction or event reference that triggered this delivery.

object

The exact JSON payload that was (or will be) sent to your endpoint.

string

ISO 8601 timestamp of the next scheduled retry. null if no retry is scheduled.

string

ISO 8601 timestamp of the successful delivery. null if not yet delivered.

string

ISO 8601 timestamp when the delivery record was created.

object

Summary of the associated subscription.

Show Subscription summary

string

Subscription ID.

string

Endpoint URL.

string

Subscription description.

object

Pagination metadata.

Show Pagination

number

Current page.

number

Records per page.

number

Total matching records.

number

Total pages.

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

string

required

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"]
    }
  }
}

{
  "status": false,
  "message": "Delivery not found"
}

Delivery statuses

Each delivery record moves through the following statuses:

Status	Description
`pending`	The delivery has been queued and no attempt has been made yet.
`retrying`	A previous attempt failed and a retry is scheduled.
`success`	Your endpoint returned a `2xx` HTTP status code.
`failed`	All 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.

Wallets

Transfers

Transactions

Webhooks

List delivery attempts

Query parameters

Response

Get a single delivery

Path parameters

Response

Delivery statuses

​List delivery attempts

​Query parameters

​Response

​Get a single delivery

​Path parameters

​Response

​Delivery statuses

List delivery attempts

Query parameters

Response

Get a single delivery

Path parameters

Response

Delivery statuses