Webhooks

$envless->webhooks->listDeliveries()

List delivery attempts for one endpoint

php
/** @return Page<WebhookDeliveryResource> */
public function listDeliveries(
    string $id,
    ?int $limit = null,
    ?int $offset = null,
    ?string $status = null,
    int|float|null $timeout = null,
): Page

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 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 failure.

Example

php
use Envless\Envless;

$envless = new Envless();

$page = $envless->webhooks->listDeliveries(
    '0194f2b1-9c3a-7c21-8f0e-2b6d4a1c5e90',
    status: 'failed',
    limit: 25,
);

foreach ($page->items as $delivery) {
    echo "{$delivery['eventType']} {$delivery['responseStatus']}", PHP_EOL;
    echo $delivery['attempts'], PHP_EOL;
}

Parameters

ParameterTypeRequiredDescription
$idstringYesEndpoint id, only its own deliveries are returned.
$statusstringNoRestricts the page to one delivery state such as failed.
$limitintNoRows per page, a whole number from 1 to 100.
$offsetintNoWhole number of deliveries to skip before the page starts.
$timeoutint|floatNoSeconds each attempt of this call may take, the response body included, before it throws Envless\Exception\NetworkException with isTimeout() true. Overrides the client's timeout for this call, and 0 turns the limit off.

Returns

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

Reads the deliveries collection. list returns one page as an Envless\Result\Page with items and pagination, listAll collects every page into an array, and iterate returns a Generator that yields one item at a time, fetching the next page only when the loop gets there.

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 TypeScript

envless.webhooks.listDeliveries()

The same method in @goenvless/sdk, with the same request, retries and errors.