# List recent events

GET /v1/webhooks/events

Source: https://cherami.to/docs/api/webhooks/list-webhook-events



{/* Generated from apps/web/openapi. Edit the contract, not this file. */}

`GET /v1/webhooks/events`

Requires an [API key](https://cherami.to/docs/api#authentication): `Authorization: Bearer YOUR_CREDENTIAL`.

Lists the account's recent events as handed to delivery, newest first, whichever webhooks they reached: event ID, type, acceptance time and the inbox and message IDs the payload carries. Use it to confirm that mail activity produced events before looking at a particular webhook's attempts, and to find an event ID when your receiver has no record of it.

Only events inside the provider's retained history window appear; absence from this list is not proof that an event never existed. An account that has never had a webhook lists nothing. An unavailable provider returns `503 webhook_history_unavailable`. Page with `limit` and `next_cursor`.

## Parameters [#parameters]

| Parameter | Location | Required | Type    | Meaning                                                                                                      |
| --------- | -------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------ |
| `limit`   | query    | No       | integer | Decimal integer without signs, whitespace or leading zeroes. `minimum`: `1` `maximum`: `100` `default`: `20` |
| `cursor`  | query    | No       | string  | Opaque cursor returned by the same listing. Stop when next\_cursor is null.                                  |

## curl example [#curl-example]

Replace resource-ID placeholders with returned IDs. Supply `CHERAMI_API_KEY` through your private shell environment.

```sh
curl --silent --show-error --include --request GET \
  "https://cherami.to/v1/webhooks/events" \
  --header "Authorization: Bearer $CHERAMI_API_KEY"
```

## Responses [#responses]

### HTTP 200 [#http-200]

Successful operation; inspect resource state and outcome fields.

* `X-Request-ID`: Support correlation ID, not an idempotency key.

Content type: `application/json`.

[WebhookEventList](#schema-webhookeventlist)

```json
{
  "events": [
    {
      "id": "66666666-6666-4666-8666-666666666666",
      "type": "message.received",
      "accepted_at": "2026-10-01T00:00:00.500Z",
      "inbox_id": "11111111-1111-4111-8111-111111111111",
      "message_id": "22222222-2222-4222-8222-222222222222"
    }
  ],
  "next_cursor": null
}
```

### HTTP 400 [#http-400]

`invalid_limit`: Use an integer from 1 to 100.

`invalid_cursor`: Use the cursor with its original resource and filters, or restart from the first page. Draft listings instead report invalid\_draft.

* `X-Request-ID`: Support correlation ID, not an idempotency key.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 401 [#http-401]

`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.

* `X-Request-ID`: Support correlation ID, not an idempotency key.
* `WWW-Authenticate`: `"Bearer"`

Content type: `application/json`.

[Error](#schema-error)

### HTTP 503 [#http-503]

`webhook_history_unavailable`: Delivery history could not be read from the webhook provider. Retry later; an unavailable history is not an empty one.

`webhooks_unavailable`: Webhook management is unavailable or the operation's outcome is unknown. Read or list webhooks before repeating a change; adding again can create a duplicate.

* `X-Request-ID`: Support correlation ID, not an idempotency key.

Content type: `application/json`.

[Error](#schema-error)

## Schema: WebhookEventList [#schema-webhookeventlist]

| Field         | Required | Type                                          | Meaning and constraints |
| ------------- | -------- | --------------------------------------------- | ----------------------- |
| `events`      | Yes      | array of [WebhookEvent](#schema-webhookevent) |                         |
| `next_cursor` | Yes      | string or null                                |                         |

## Schema: WebhookEvent [#schema-webhookevent]

| Field         | Required | Type                                         | Meaning and constraints                                                                                  |
| ------------- | -------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `id`          | Yes      | string                                       | Cherami event ID: the stable logical identity also carried as payload id. Deduplicate on it.             |
| `type`        | Yes      | [WebhookEventType](#schema-webhookeventtype) |                                                                                                          |
| `accepted_at` | Yes      | string                                       | When delivery accepted the event, not the mail transition time inside the payload. `format`: `date-time` |
| `inbox_id`    | Yes      | string or null                               |                                                                                                          |
| `message_id`  | Yes      | string or null                               |                                                                                                          |

## Schema: WebhookEventType [#schema-webhookeventtype]

message.received: received mail became ready to read. message.sent: provider acceptance of a send was persisted; not delivery.

`"message.received"` or `"message.sent"`

## Schema: Error [#schema-error]

| Field   | Required | Type   | Meaning and constraints |
| ------- | -------- | ------ | ----------------------- |
| `error` | Yes      | object |                         |

### `error` fields [#error-fields]

| Field     | Required | Type   | Meaning and constraints                                                                       |
| --------- | -------- | ------ | --------------------------------------------------------------------------------------------- |
| `code`    | Yes      | string | Programmatic error code. Handle unrecognized codes by status and operation-specific recovery. |
| `message` | Yes      | string | Human-readable context, not a stable string to match.                                         |

[HTTP conventions, errors and pagination](https://cherami.to/docs/api/errors) · [Download OpenAPI 3.1](https://cherami.to/openapi.json)