Webhooks

envless.webhooks.listDeliveries()

List delivery attempts for one endpoint

ts
listDeliveries(id: string, options?: DeliveryListOptions): Promise<Page<WebhookDeliveryResource>>

Returns one page of delivery attempts for a single endpoint, newest first. This is the log you read when a receiver stops seeing events.

A delivery starts pending, moves to processing, then settles as succeeded or failed. attempts counts tries so far up to 5, while responseStatus and error record what the receiver said. Anything outside 2xx, a 3xx redirect, or a request past the 10 second timeout is a failure. Use options.status to narrow the log to one state, and note that an unrecognised value is a 400 rather than an empty page.

Response bodies are omitted from every row here. getDelivery is the only way to see responseBody, and that is usually the field that explains a rejection.

Example

ts
const page = await envless.webhooks.listDeliveries('0194f2b1-9c3a-7c21-8f0e-2b6d4a1c5e90', {
    status: 'failed',
    limit: 25
})

console.log(page.items.map((delivery) => [delivery.eventType, delivery.responseStatus, delivery.attempts]))

Parameters

ParameterTypeRequiredDescription
idstringYesEndpoint id, only its own deliveries are returned.
options.statusstringNoRestricts the page to one delivery state such as failed.
options.limitnumberNoRows per page, a whole number from 1 to 100.
options.offsetnumberNoWhole number of deliveries to skip before the page starts.
options.signalAbortSignalNoCancels the request.

Returns

Page<WebhookDeliveryResource> with items and a pagination envelope counting the matching deliveries.

Reads the deliveries collection. list returns one page as { items, pagination }, listAll collects every page into an array, and iterate streams one item at a time without buffering the whole set.

Worth knowing

  • One event fanned out to several endpoints produces several deliveries, and a redelivery reuses the source event id, so the event id is not unique. De-duplicate on it in your handler.
  • A 404 webhook.not_found means the endpoint id is wrong, not that the log is empty.

Required scopes

webhooks:read

Underlying endpoint

GET /webhooks/{id}/deliveries

Request and response schema, every error code, and a live playground.

In Python

envless.webhooks.list_deliveries()

The same method in envless-sdk, the Python SDK, with the same request, retries and errors.

In Ruby

Envless.webhooks.list_deliveries

The same method in envless-sdk, the Ruby gem, with the same request, retries and errors.

In PHP

$envless->webhooks->listDeliveries()

The same method in envless/sdk, the PHP SDK, with the same request, retries and errors.