---
title: "Webhook Deliveries"
description: "Inspect recent webhook delivery outcomes without exposing event payloads or transcripts."
---

Use the delivery history endpoint to confirm whether ThunderPhone attempted a webhook,
the safe outcome category, and whether another retry is scheduled. It merges the
recommended [webhook endpoint system](/webhooks/endpoints) with the legacy single-URL
call-finished webhook.

<Note>
  Delivery history never includes the webhook payload. Call-completion payloads can
  contain transcripts, so this endpoint returns delivery metadata only. URLs omit
  paths, user credentials, query strings, and fragments. Responses include only an
  HTTP status and an allowlisted failure category, never stored error or response text.
</Note>

The same recent history appears in the dashboard under **Agents → select an agent →
Webhooks → Recent deliveries**. Each row identifies the endpoint label and the safe URL
origin used by its latest attempt.

This history is recent operational state, not an immutable audit log. The endpoint system
stores only the latest outcome for each queued delivery, and deleting an endpoint also
deletes its delivery rows. Retrieve any records you need to retain before deleting an endpoint.

## List deliveries

```http
GET /v1/developer/webhook-deliveries
```

Requires an organization admin. Authenticate with a server API key, an admin session
token, or OAuth authorized for the organization with `integrations:read`. OAuth access
still uses the current user's live organization role, so members cannot read this route.

<CodeGroup>
```bash cURL
curl "https://api.thunderphone.com/v1/developer/webhook-deliveries?status=retrying&limit=50" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

```python Python
deliveries = requests.get(
    "https://api.thunderphone.com/v1/developer/webhook-deliveries",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    params={"agent_id": 42, "since": "2026-09-18T00:00:00Z"},
).json()
```
</CodeGroup>

### Filters

| Parameter | Type | Description |
|-----------|------|-------------|
| `agent_id` | integer | Deliveries associated with one agent |
| `endpoint_id` | UUID or `legacy` | One endpoint, or only the legacy single-URL webhook |
| `event_type` | string | Exact event type, such as `telephony.complete` |
| `status` | string | `delivered`, `retrying`, or `failed` |
| `since` | RFC 3339 timestamp | Result-change window; defaults to 7 days ago and is clamped to at most 30 days ago |
| `limit` | integer | Page size, 1–50; defaults to 50 |
| `cursor` | string | Opaque `next_cursor` from the previous page; reuse it only with the same organization, filters, `since`, and `limit` |

### Response

```json
{
  "results": [
    {
      "source": "endpoint",
      "endpoint_id": "00000000-0000-4000-8000-000000000001",
      "endpoint_label": "n8n production",
      "url": "https://n8n.example.com",
      "event_type": "telephony.complete",
      "call_id": 1001,
      "status": "retrying",
      "attempt_count": 2,
      "http_status": 404,
      "failure_category": "http_error",
      "last_attempt_at": "2026-09-19T16:20:00Z",
      "next_retry_at": "2026-09-19T16:25:00Z"
    }
  ],
  "limit": 50,
  "has_more": false,
  "next_cursor": null
}
```

`source` is `endpoint` for the endpoint-based system and `legacy` for the
single-URL call-finished webhook. Legacy rows use `endpoint_id: "legacy"`.
`url` is the sanitized origin used by the most recent recorded attempt. It is
`null` for rows created before destination snapshots were available.
`http_status` can be `null` when no response was received or the legacy success
path did not retain the status code. `failure_category` is `timeout`, `dns`, `tls`,
`connection`, `http_error`, `other`, or `null` when there is no failure. Legacy rows
created before destination snapshots were added return a generic label and `url: null`.
`next_retry_at` is present only while the delivery is retrying.

### Interpreting common failures

- `404` from n8n: confirm the workflow is active, the webhook uses `POST`, and
  the production URL is configured instead of n8n's test URL.
- `401` or `403`: the destination rejected authentication. Check its credentials,
  authorization policy, and ThunderPhone signature verification.
- `timeout`: the destination did not answer before the webhook timeout. Check its
  availability and response time.
- `dns`: check that the configured hostname resolves publicly.
- `tls`: check the certificate chain, hostname, and certificate expiry.
- `connection`: check that the destination accepts and keeps HTTPS connections.
- `other`: the stored failure could not be safely classified; no raw response is exposed.