Webhooks & logs

Three operational logs help an operator debug deliveries and trace what happened: the webhook delivery log, the append-only audit log, and the gateway-callback evidence log. All three are session-authenticated admin surfaces gated by RBAC authorities — they are not part of the app-facing API.

These are read-and-act surfaces for operators. App developers integrating webhook consumers should start with the Webhooks guide.

All responses use the standard envelope:

{
  "data": <payload | null>,
  "meta": { "success": true, "message": null, "errorCode": null, "timestamp": "2026-06-30T12:00:00Z" },
  "pagination": { "page": 0, "size": 20, "totalElements": 42, "totalPages": 3 }
}

The examples below show just the data payload after the first one. Admin endpoints authenticate with a session bearer token, not an API key:

-H "Authorization: Bearer SESSION_TOKEN"

Webhook delivery log

GET /api/v1/admin/webhooks lists outbox events with their delivery state across every app the caller is scoped to. The coarse authority audit:read is checked on the endpoint, then the result set is narrowed to the apps the operator can see (RBAC-4) — one app never appears in another operator's view. See app isolation.

Query parameters

Every filter is optional; a missing filter leaves that dimension unconstrained.

See pagination & filtering for the shared page / size / sortBy / order / paginate conventions.

The full set of catalogue names you can pass as type:

PAYMENT_SUCCEEDED  PAYMENT_FAILED  PAYMENT_CANCELLED  PAYMENT_EXPIRED
REFUND_PENDING  REFUND_SUCCEEDED  REFUND_FAILED
INVOICE_ISSUED  INVOICE_PARTIALLY_PAID  INVOICE_PAID  INVOICE_VOIDED
SUBSCRIPTION_CREATED  SUBSCRIPTION_ACTIVATED  SUBSCRIPTION_TRIAL_WILL_END
SUBSCRIPTION_RENEWED  SUBSCRIPTION_PAYMENT_SUCCEEDED  SUBSCRIPTION_PAYMENT_FAILED
SUBSCRIPTION_PAST_DUE  SUBSCRIPTION_CANCELED  SUBSCRIPTION_PAUSED
SUBSCRIPTION_RESUMED  SUBSCRIPTION_ENTITLEMENTS_UPDATED

WebhookEventDto (response row)

Each delivery-log row is a WebhookEventDto. Null fields are omitted from the JSON.

Example — failed subscription renewals

curl "http://localhost:8080/api/v1/admin/webhooks?type=SUBSCRIPTION_RENEWED&deliveryStatus=FAILED&size=20" \
  -H "Authorization: Bearer SESSION_TOKEN"

{
  "data": [
    {
      "id": 90817,
      "applicationId": 42,
      "applicationName": "Acme Storefront",
      "mode": "LIVE",
      "type": "subscription.renewed",
      "schemaVersion": 1,
      "payload": "{\"subscription_id\":\"sub_8f3a\",\"amount\":150000,\"currency\":\"BDT\"}",
      "deliveryStatus": "FAILED",
      "attempts": 6,
      "lastResponseStatus": 503,
      "lastError": "503 Service Unavailable",
      "lastAttemptAt": "2026-06-30T09:41:12",
      "createdAt": "2026-06-30T08:55:00",
      "updatedAt": "2026-06-30T09:41:12"
    }
  ],
  "meta": { "success": true, "message": null, "errorCode": null, "timestamp": "2026-06-30T12:00:00Z" },
  "pagination": { "page": 0, "size": 20, "totalElements": 1, "totalPages": 1 }
}

Note the row above has deliveryStatus: FAILED and attempts: 6, and no nextAttemptAt or deliveredAt — it is parked. The amount of 150000 in the payload is paisa: 1,500.00 BDT. See money.

Delivery status & the retry lifecycle

A captured event starts PENDING and is driven by the background delivery loop. The status field has exactly three values:

Two conditions park on the first attempt instead of consuming the retry budget. Both are things only an operator or the merchant can fix, so re-deriving the same answer thirteen more times over six hours would waste claim capacity and — worse — delay the moment anyone notices, because the row stays non-terminal until the budget drains:

The delivery loop is configured in app.webhook.delivery.*. The values that govern when a row parks:

Backoff before the n-th retry (0-based) is min(maxBackoff, initialBackoff · 2ⁿ), then jittered by ±jitterRatio, giving a retry horizon of roughly 6 hours across all 14 attempts. After maxAttempts failed attempts the event parks. The two immediate-park conditions above bypass this schedule entirely.

Webhook endpoints and URL requirements

An application configures up to five webhook endpoints per mode — five TEST and five LIVE — at /api/v1/admin/apps/{id}/webhook-endpoints. Each is an independent row with its own URL, its own signing secret, its own enabled state and its own event subscription.

A captured event fans out to every enabled endpoint of its own mode, producing one delivery row per endpoint. Those rows have independent statuses, attempt counts and retry schedules, so one merchant consumer failing never holds up another.

LIVE events are never transmitted over an unencrypted connection. The delivery signature proves the payload was not altered; it does not keep it private, and a plaintext LIVE payload exposes amounts, customer references and event types to anyone on the network path.

Enforcement

Because endpoints now carry their own mode, the TLS rule is stated per mode. That was not possible before: with one column serving both modes there was no "the LIVE URL" to hold to a stricter standard, so the write-time rule had to be "https, always" and the TEST plaintext allowance was theoretical.

Endpoints backfilled by V38 whose inherited URL was not https are created DISABLED in LIVE. Those events already parked, so nothing is lost — but the merchant now sees a disabled endpoint in the dashboard rather than a quiet trail of parked rows.

Signing secrets

Each endpoint has its own, so one can be rotated or revoked without invalidating every other consumer, and a test consumer's key can never verify live traffic. A secret is returned exactly twice — by create and by rotate — and by no read endpoint. Both are gated on app:manage plus recent re-auth, and both are audited.

Relaxing it (self-hosted / sandbox)

Plaintext endpoints are permitted by widening the allowlist the transport already uses — app.webhook.delivery.http.allowed-schemes, env WEBHOOK_DELIVERY_SCHEMES:

WEBHOOK_DELIVERY_SCHEMES=https,http

The shipped default is https alone. This is deliberately the same key the delivery transport reads rather than a second switch, so the two can never be set to disagree.

A URL stored before this rule existed, or written directly into the column, is not retroactively rejected — it is caught at delivery time by the runtime check, which remains in place as the last line rather than the only one.

Re-send a parked event

POST /api/v1/admin/webhooks/{id}/resend re-queues one parked, failed, or still-pending event for re-delivery and returns its re-queued state.

This action is gated by app:manage. The authority is checked coarsely on the endpoint, then re-checked app-scoped against the event's owning app inside the use case (RBAC-4). It is a sensitive action and additionally requires a recent re-authentication:

• Unknown event id → 404 (RESOURCE_NOT_FOUND).
• Operator lacks app:manage for that event's app → 403 (FORBIDDEN).
• No recent re-authentication → 403 (FORBIDDEN).
• The event is being delivered right now → 409. Retry a few seconds later.

Example

curl -X POST "http://localhost:8080/api/v1/admin/webhooks/90817/resend" \
  -H "Authorization: Bearer SESSION_TOKEN"

A successful re-send returns the re-queued row — deliveryStatus back to PENDING, attempts reset to 0, deliveredAt cleared. This is the state before the next sweep picks it up, not a delivery outcome:

{
  "id": 90817,
  "applicationId": 42,
  "applicationName": "Acme Storefront",
  "mode": "LIVE",
  "type": "subscription.renewed",
  "schemaVersion": 1,
  "payload": "{\"subscription_id\":\"sub_8f3a\",\"amount\":150000,\"currency\":\"BDT\"}",
  "deliveryStatus": "PENDING",
  "attempts": 0,
  "lastResponseStatus": 503,
  "lastError": "503 Service Unavailable",
  "lastAttemptAt": "2026-06-30T09:41:12",
  "createdAt": "2026-06-30T08:55:00",
  "updatedAt": "2026-06-30T12:01:30"
}

Refresh the delivery log to see the outcome. If the consumer is still down the row stays PENDING with a new nextAttemptAt and works through its fresh 14-attempt budget, then parks FAILED again with lastError and lastResponseStatus describing the latest failure.

Audit log

GET /api/v1/admin/audit-logs (requires audit:read) is the append-only trail of sensitive actions — credential rotation/revocation, gateway overrides, user and role management, refund approvals, and webhook re-sends (WEBHOOK_RESENT). Filter by actorType, actorId, action, targetType, and targetId, with the same page / size / sortBy / order / paginate conventions.

actorType is the enum name — USER (a human admin), APP (a client application acting via its API key), or SYSTEM (an automated action).

Each row is an AuditLogDto:

Gateway-callback evidence

GET /api/v1/admin/gateway-callbacks (requires audit:read) records every inbound gateway callback (IPN) the service received, with the decision it applied — useful when a payment's state and the gateway appear to disagree. Filter by mode, outcome, reference, matchedPaymentId, gateway, and signatureValid.

Callback evidence is forensic data with no single owning app (an unmatched callback matched no payment), so — like the audit trail — it is not app-scope-narrowed; the audit:read authority is the only gate.

Each row is a GatewayCallbackLogDto:

The outcome enum name explains what the handler did:

An outcome of SIGNATURE_INVALID or DUPLICATE here explains why a callback did not move a payment, without you having to dig into the gateway's own dashboard. A run of SETTLED_AFTER_EXPIRY rows is worth acting on rather than just noting: it means the checkout window is shorter than customers are actually taking, and every one of those is a merchant who was told "expired" and then "succeeded". Raise the app's Checkout window in its settings. See reconciliation for matching settled gateway records against the ledger.

Related