# List failed webhook deliveries

`GET /webhook.deliveries`

## Description

List recent **failed** webhook delivery attempts for the authenticated API
client, newest first. Use this to debug a misbehaving endpoint and to find
the events you need to replay: successful (2xx) deliveries are never
recorded, so every row here is a delivery your endpoint did not accept.

Timeouts are first-class failures: `statusCode` is `0` and `error` is
`timeout`. For HTTP error responses, a truncated copy of your server's
response body is included to aid debugging. The request payload is never
stored — to recover the data, re-fetch the underlying resource (e.g. via
`chat.history`) using the delivery's `messageId`/`event` context.

Results are strictly scoped to the caller's own subscriptions and retained
for roughly 30 days.

**Access:** Organization and Personal.

**Required scope:** `webhook:read`

---

**OpenAPI Spec:** [webhooks-v1.json](https://developer.ro.am/webhooks-v1.json)

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `webhook` | query | string | No | Only return deliveries for this webhook subscription ID. |
| `event` | query | string | No | Only return deliveries for this event name (e.g. `chat.message`). |
| `after` | query | string | No | Only return deliveries after this time (RFC3339 or `YYYY-MM-DD`). Results switch to oldest-first. |
| `before` | query | string | No | Only return deliveries before this time (RFC3339 or `YYYY-MM-DD`). |
| `limit` | query | integer | No | Maximum number of deliveries to return. |
| `cursor` | query | string | No | Opaque pagination cursor from a previous response's `nextCursor`. |

## Responses

### 200 - Failed delivery attempts for the caller's subscriptions.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `deliveries` | object[] | Yes | Failed delivery attempts, newest first. Empty array if none. |
| `nextCursor` | string | No | Opaque cursor for the next page. Omitted on the last page. |

**deliveries** (array item):

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `timestamp` | string | Yes | When the delivery was attempted (RFC3339 UTC). |
| `webhookId` | string | No | ID of the webhook subscription. Omitted for static (UI-configured) destinations. |
| `event` | string | Yes | The event name that was being delivered (e.g. `chat.message`). |
| `url` | string | Yes | The destination URL that was called. |
| `statusCode` | integer | Yes | HTTP status code returned by the destination. `0` for connection errors and timeouts. |
| `error` | string | Yes | Failure classification (e.g. `timeout`, `http_4xx`, `http_5xx`, `connection`). |
| `response` | string | No | Truncated response body from the destination, present for HTTP error statuses. |
| `durationMs` | integer | Yes | How long the delivery attempt took, in milliseconds. |
| `messageId` | string | No | ID of the message that triggered the event, when applicable. |
| `success` | boolean | Yes | Always `false` — only failed deliveries are recorded. |


#### Example Response

```json
{
  "deliveries": [
    {
      "timestamp": "2026-07-19T18:23:45Z",
      "webhookId": "19c6401f-6d02-4d8c-87c5-9fc45f02f4b5",
      "event": "chat.message",
      "url": "https://example.com/hooks/messages",
      "statusCode": 0,
      "error": "timeout",
      "durationMs": 3000,
      "success": false
    },
    {
      "timestamp": "2026-07-19T18:22:10Z",
      "webhookId": "19c6401f-6d02-4d8c-87c5-9fc45f02f4b5",
      "event": "chat.message",
      "url": "https://example.com/hooks/messages",
      "statusCode": 503,
      "error": "http_5xx",
      "response": "upstream unavailable",
      "durationMs": 187,
      "success": false
    }
  ]
}
```

### 400 - Invalid query parameter (e.g. malformed `webhook` UUID or `cursor`).

### 401 - Presented invalid authentication credentials.

### 500 - An internal error occurred.

---

*Machine-readable API documentation.*
*Full documentation: https://developer.ro.am/docs/webhooks/webhook-deliveries*