List DLQ Messages

Use this endpoint to list messages currently in the webhook dead-letter queue, scoped to the caller’s tenant. The tenant is derived from the bearer JWT (tenantId claim), never from a request header.

This route is only mounted when authentication is enabled and a DLQ inspector is configured. Otherwise it is not exposed and any request is rejected with 503.

GET /v1/transfers/webhooks/dlq

List DLQ Messages

cURL

curl --request GET \
  --url https://plugin-br-bank-transfer.sandbox.lerian.net/v1/transfers/webhooks/dlq \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Organization-Id: <x-organization-id>'

200

page

{
  "messages": [
    {
      "messageId": "019c96a0-d1d2-7e3f-4a5b-6c7d8e9f0a1b",
      "routingKey": "webhook.transfer.completed",
      "deathReason": "rejected",
      "failureReason": "HTTP 500 from subscriber",
      "tenantId": "11111111-1111-1111-1111-111111111111",
      "transferId": "019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d",
      "eventType": "transfer.completed",
      "correlationId": "019c96a0-cc10-7abc-d1e2-3f4a5b6c7d8e",
      "retryCount": 5,
      "manualRetryCount": 1,
      "timestamp": "2026-02-01T15:35:00-03:00"
    }
  ],
  "totalCount": 1,
  "returnedCount": 1,
  "hasMore": false
}

Authorizations

Authorization · string · header · required

JWT Bearer token authentication. The token must include a tenantId claim that matches the X-Organization-Id header.

Headers

X-Organization-Id · string<uuid> · required

Organization ID used as the tenant identifier. All data is scoped to this organization. Must match the JWT tenantId claim when authentication is enabled.

Query Parameters

limit · integer · default: 50

Maximum number of messages to return.

Required range: 1 <= x <= 200

offset · integer · default: 0

Number of messages to skip for pagination.

Required range: x >= 0

Response

200

application/json

Indicates the DLQ messages page was returned successfully.

messages · object[] · required

Show child attributes

totalCount · integer · required

Tenant-filtered message count visited during this scan. When hasMore is true this is a best-effort lower bound on the true DLQ depth for this tenant, not the full count.

Required range: x >= 0

Example:

1

returnedCount · integer · required

Number of messages in this page after offset and limit are applied.

Required range: x >= 0

Example:

1

hasMore · boolean

True when the inspector stopped scanning early after filling the current page.

Example:

false

warning · string

Set when pagination may be non-deterministic (e.g., concurrent access shifts ordering).

Example:

"pagination may be non-deterministic under concurrent access"