# List webhook deliveries

`GET https://app.booksbyinstant.com/api/integrator/v1/webhook/deliveries`

The integrator's deliveries, newest first, a page at a time. There is no replay: a failed delivery is not sent again, so read what it was about through the customer API.

operationId `listDeliveries`; tag Webhook.

## Example request

cURL:

```bash
curl -X GET 'https://app.booksbyinstant.com/api/integrator/v1/webhook/deliveries' \
  -H "Authorization: Bearer $INTEGRATOR_CREDENTIAL"
```

JavaScript:

```javascript
// Node 18 or later, in an ES module (.mjs), which allows the top-level await.
const res = await fetch("https://app.booksbyinstant.com/api/integrator/v1/webhook/deliveries", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.INTEGRATOR_CREDENTIAL}`,
  },
});
const data = await res.json();
```

Python:

```python
import os
import requests

res = requests.get(
    "https://app.booksbyinstant.com/api/integrator/v1/webhook/deliveries",
    headers={
        "Authorization": f"Bearer {os.environ['INTEGRATOR_CREDENTIAL']}",
    },
)
data = res.json()
```

## Authorization

- Bearer token `live_<100 hex>`: `Authorization: Bearer <secret>`. A 401 answers `WWW-Authenticate: Bearer realm="instant-integrator-api"`.

## Query parameters

- `limit` (integer; from `1` to `200`; default `50`): How many to answer: a whole number from 1 to 200, without a leading zero.
- `cursor` (string · uuid): The nextCursor of the previous page.
- `status` (string; one of `pending`, `delivered`, `failed`): Only the deliveries in this state.

## Responses

### 200

A page of deliveries.

`application/json`: object

- `items` (array of object; required)
  - `id` (string · uuid; required): The delivery's id, which is its payload's id and Instant-Event-Id.
  - `kind` (string; required; one of `reply.ready`, `run.finished`, `approval.due`, `task.input_needed`, `ping.raised`, `browser.takeover_needed`, `connection.expired`, `customer.paused`, `customer.resumed`, `connection.synced`, `link.finished`, `docs.updated`)
  - `customerId` (string · uuid or null; required): The customer it is about, or null for docs.updated.
  - `customerReference` (string or null; required): The integrator's reference for the customer, or null for docs.updated.
  - `memberId` (string · uuid or null; required): The member it is for, or null for connection.expired, connection.synced, link.finished, customer.paused, customer.resumed and docs.updated.
  - `item` (one of 4 shapes; required): What it is about, or null for docs.updated.
    - either object
      - `kind` (string; required; always `run`)
      - `actionId` (string · uuid; required): The recurring action or background work.
      - `runId` (string · uuid; required): The run.
    - or object
      - `kind` (string; required; one of `approval`, `task`, `ping`, `document`, `partner`, `payment`, `thread`, `customer`, `bank_connection`)
      - `id` (string · uuid): The subject's id; absent when it is not a UUID.
    - or object
      - `kind` (string; required; always `bank_connection`)
      - `id` (string · uuid; required): The bank connection.
      - `outcome` (string; required; one of `completed`, `failed`): connection.synced only: completed when every account was read (from the first day through yesterday for a backfill); failed when the consent ran out first, or a read asked for failed.
    - or object
      - `kind` (string; required; always `bank_link`)
      - `id` (string · uuid; required): The bank connection link.
      - `outcome` (string; required; one of `connected`, `cancelled`, `failed`, `expired`): link.finished only: connected when the consent gave a connection; cancelled when the person cancelled; failed when the bank or its provider refused, or Instant could not complete the consent; expired when nobody opened the link in time, or its consent never came back.
  - `status` (string; required; one of `pending`, `delivered`, `failed`): pending until a receiver answers 2xx (delivered), or until the 7th attempt fails, the webhook is removed or 30 days pass (failed).
  - `attempts` (integer; required; at least `0`): How many attempts were made, at most 7.
  - `lastError` (string or null; required; matches `^(http_[0-9]{3}|timeout|network|redirect|url_refused|webhook_removed|expired)$`): Why the last attempt failed: http_&lt;status>, timeout, network, redirect, url_refused, webhook_removed or expired; null when none did.
  - `createdAt` (string · date-time; required): When the delivery was created. ISO 8601 in UTC with milliseconds, such as 2026-11-06T10:00:00.000Z.
  - `deliveredAt` (string · date-time or null; required): When a receiver answered 2xx, or null. ISO 8601 in UTC with milliseconds, such as 2026-11-06T10:00:00.000Z.
  - `nextAttemptAt` (string · date-time or null; required): When the next attempt is due while pending; otherwise null. ISO 8601 in UTC with milliseconds, such as 2026-11-06T10:00:00.000Z.
- `nextCursor` (string · uuid or null; required): The cursor of the next page, or null on the last page.

Example, built from the schema:

```json
{
  "items": [
    {
      "id": "01900000-0000-7000-8000-000000000000",
      "kind": "reply.ready",
      "customerId": "01900000-0000-7000-8000-000000000000",
      "customerReference": "string",
      "memberId": "01900000-0000-7000-8000-000000000000",
      "item": {
        "kind": "run",
        "actionId": "01900000-0000-7000-8000-000000000000",
        "runId": "01900000-0000-7000-8000-000000000000"
      },
      "status": "pending",
      "attempts": 0,
      "lastError": "string",
      "createdAt": "2026-01-15T09:30:00.000Z",
      "deliveredAt": "2026-01-15T09:30:00.000Z",
      "nextAttemptAt": "2026-01-15T09:30:00.000Z"
    }
  ],
  "nextCursor": "01900000-0000-7000-8000-000000000000"
}
```

### 400

A query parameter is unknown or invalid.

`application/json`: object; `Error`

Every answer that is not a success.

- `error` (string; required): Instant's sentence for people. A 4xx keeps the refusal's own sentence; a 5xx always says "Instant is temporarily unavailable. Please try again shortly."
- `code` (string; required): Stable, and what a caller branches on: VALIDATION_ERROR (400), UNAUTHENTICATED (401), FORBIDDEN (403), NOT_FOUND (404), CONFLICT (409), LIMIT_EXCEEDED (413), UNSUPPORTED_MEDIA_TYPE (415), UNREADABLE_FILE (422), RATE_LIMITED (429) and UNAVAILABLE (5xx). More codes may be added; treat one you do not know by its status.
- `retryAfter` (integer; at least `1`): Seconds to wait before retrying, also sent as the `Retry-After` header. Present only when there is a wait, as on a 429.
- `existingId` (string · uuid): On a 409 that names the object already there, such as a customer with that reference: its id.

Example, built from the schema:

```json
{
  "error": "string",
  "code": "VALIDATION_ERROR",
  "retryAfter": 1,
  "existingId": "01900000-0000-7000-8000-000000000000"
}
```

### 401

The credential is missing, malformed, unknown, revoked or rotated, or its integrator is disabled. All of these answer the same way.

Headers:

- `WWW-Authenticate` (string): Bearer realm="instant-integrator-api"

`application/json`: the `Error` object, as in 400.

### 5XX

Instant is temporarily unavailable. Retry later, with backoff.

`application/json`: the `Error` object, as in 400.

---

Page: https://booksbyinstant.com/docs/list-deliveries/ · Overview: https://booksbyinstant.com/docs/index.md