Review notification logs with the API

Payabli records a log entry for every notification it sends, whether that’s a webhook delivery, an email, an SMS, or a generated report. Use the notification logs API to confirm a notification reached its destination, find out why one didn’t, and send it again from your own tooling.

Considerations

Keep these considerations in mind when working with the notification logs API:

• The endpoints require the notifications_read or notifications_create permission. Retrying a notification requires notifications_create.
• Each search must scope to an organization or a paypoint, so pass either orgId or paypointId.
• A search window can’t span more than 30 days between startDate and endDate.
• Payabli can’t retry some notifications at all, such as password-reset emails.

Search notification logs

Send a POST request to /v2/notificationlogs to search for notifications within a date range. Filter by event, delivery outcome, and owning entity, and page through the results. See the API reference for full documentation.

This example returns the first 20 successful approvedpayment notifications for an organization in January 2024:

curl -X POST "https://api-sandbox.payabli.com/api/v2/notificationlogs?PageSize=20" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "startDate": "2024-01-01T00:00:00Z",
  "endDate": "2024-01-31T23:59:59Z",
  "notificationEvent": "approvedpayment",
  "succeeded": true,
  "orgId": 123
}'

A successful response returns an array of matching log entries, newest first:

[
  {
    "organizationLogo": "https://example.com/org-logo.png",
    "organizationFavIcon": "https://example.com/org-favicon.png",
    "paypointLogo": "https://example.com/paypoint-logo.png",
    "notificationType": 1,
    "organizationName": "The Pilgrim Planner",
    "paypointName": "Pilgrim Planner",
    "requestId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "orgId": 123,
    "paypointId": 3040,
    "notificationEvent": "approvedpayment",
    "target": "https://webhook.example.com/payments",
    "responseStatusCode": 200,
    "responseStatus": "OK",
    "success": true,
    "jobData": "{\"transactionId\":\"txn_123\"}",
    "createdDate": "2024-01-15T10:30:00Z",
    "successDate": "2024-01-15T10:30:05Z",
    "lastFailedDate": null,
    "isInProgress": false
  }
]

Each entry’s notificationType identifies the delivery method: 1 (Email), 2 (SMS), or 3 (Webhook).

Filter the search

Pass any of these fields in the request body to narrow the results:

Set the page size and page with the PageSize and Page query parameters. To triage failures, filter with succeeded: false and read the delivery fields on each entry.

Read the delivery outcome

Three fields tell you what happened to a delivery:

• success is true when the target accepted the delivery and false when it didn’t.
• responseStatusCode is the HTTP status code the target returned, such as 200 or 500. It’s 0 when the target sent no response.
• responseStatus is the status message, such as OK, Dropped, or No response received from server.

Read successDate and lastFailedDate together to see the delivery’s history. A lastFailedDate with no successDate means the delivery has failed and hasn’t succeeded since. Automatic retries may still be running, so check isInProgress before you step in.

Get notification details

Send a GET request to /v2/notificationlogs/{uuid} to retrieve one entry with the full request and response Payabli captured. See the API reference for full documentation.

curl https://api-sandbox.payabli.com/api/v2/notificationlogs/550e8400-e29b-41d4-a716-446655440000 \
     -H "Authorization: Bearer <token>"

Alongside the core notification fields, the detail response adds what left Payabli and what came back:

• webHeaders are the custom headers Payabli sent with the notification, if any.
• responseHeaders are the headers the target returned, or null when the target sent no response.
• responseContent is the body the target returned, or empty when the target sent no response.

{
  "webHeaders": [
    {
      "key": "Content-Type",
      "value": "application/json"
    },
    {
      "key": "User-Agent",
      "value": "PaymentSystem/1.0"
    }
  ],
  "responseHeaders": [
    {
      "key": "Content-Type",
      "value": [
        "application/json"
      ]
    },
    {
      "key": "X-Request-ID",
      "value": [
        "req_abc123"
      ]
    }
  ],
  "responseContent": "{\"status\":\"received\",\"id\":\"wh_123\"}",
  "organizationName": "The Pilgrim Planner",
  "paypointName": "Pilgrim Planner",
  "requestId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "orgId": 123,
  "paypointId": 3040,
  "notificationEvent": "approvedpayment",
  "target": "https://webhook.example.com/payments",
  "responseStatusCode": 200,
  "responseStatus": "OK",
  "success": true,
  "jobData": "{\"transactionId\":\"txn_123\"}",
  "createdDate": "2024-01-15T10:30:00Z",
  "successDate": "2024-01-15T10:30:05Z",
  "lastFailedDate": null,
  "isInProgress": false
}

The webHeaders array shows those custom headers exactly as Payabli sent them.

Tell a rejected delivery from an unreachable one

The responseStatusCode separates the two failures that look alike in a search:

• A status code, such as 401 or 500, means your endpoint received the request and rejected it. Read responseContent for what your server returned, then fix the endpoint before you retry.
• A responseStatusCode of 0, with responseStatus reading No response received from server., means Payabli couldn’t reach the endpoint. Confirm the URL is right and publicly reachable before you retry.

Retry a failed notification

Payabli retries a failed webhook twice on its own, waiting 5 minutes between tries. After the second failed retry, it marks the delivery failed and leaves it for you to retry. Fix whatever caused the failure first, because a retry to an endpoint that’s still broken fails the same way.

Send a GET request to /v2/notificationlogs/{uuid}/retry to retry a single notification. See the API reference for full documentation.

curl https://api-sandbox.payabli.com/api/v2/notificationlogs/550e8400-e29b-41d4-a716-446655440000/retry \
     -H "Authorization: Bearer <token>"

Payabli resends the notification to its target and returns a confirmation message, not the updated log entry. Search for the notification again to confirm whether successDate fills in.

{
  "message": "Notification retry succeeded."
}

Retry several notifications

Send a POST request to /v2/notificationlogs/retry with an array of up to 50 notification IDs to retry them together. See the API reference for full documentation.

curl -X POST https://api-sandbox.payabli.com/api/v2/notificationlogs/retry \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '[
  "550e8400-e29b-41d4-a716-446655440000",
  "550e8400-e29b-41d4-a716-446655440001",
  "550e8400-e29b-41d4-a716-446655440002"
]'

A bulk retry covers only failed webhooks and excludes emails. It runs asynchronously, so the response confirms only that Payabli accepted the request. Search the logs again after 2 to 5 minutes and check whether successDate fills in to confirm each delivery landed.

Related resources

See these related resources to help you get the most out of Payabli.