> Documentation index: https://docs.kiste.run/llms.txt, a list of every page in this documentation.

# Events, webhooks and alerts

> The durable event stream of your account, signed webhook deliveries and account alerts.

The durable event stream of your account, signed webhook deliveries and account alerts.

## Read events

`GET /v1/events`

The durable event stream of your account, oldest first, after the cursor `after`. Pass the returned `next_cursor` as the next `after`. With `wait_ms` the call waits up to that long for new events, so a loop of calls follows the stream without missing anything.

**Query parameters:**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `after` | integer | no | Return events after this cursor. Default 0, the beginning. |
| `limit` | integer | no | Maximum number of events, 1 to 200. |
| `wait_ms` | integer | no | Wait up to this many milliseconds for new events when there are none yet, at most 25000. |
| `resource_type` | string | no | Only events of this resource type, such as `instance`. |
| `resource_id` | string | no | Only events of this resource. |

```bash
curl -sS "https://kiste.run/v1/events" \
  -H "Authorization: Bearer $KISTE_TOKEN"
```

**Responses:**

- `200` OK. Body: [WatchEventsResponse](https://docs.kiste.run/api/schemas.md#watcheventsresponse)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

## List webhooks

`GET /v1/webhooks`

Your webhook endpoints.

```bash
curl -sS "https://kiste.run/v1/webhooks" \
  -H "Authorization: Bearer $KISTE_TOKEN"
```

**Responses:**

- `200` OK. Body: list of [WebhookEndpointResponse](https://docs.kiste.run/api/schemas.md#webhookendpointresponse)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

## Create a webhook

`POST /v1/webhooks`

Creates an endpoint that receives the listed event types as signed HTTPS POST requests. The answer contains the signing secret (`whsec_…`) once. The URL must be HTTPS on port 443 and resolve to public addresses. Creating an endpoint also raises a `webhook_created` alert. At most 10 endpoints and 32 event types each.

```bash
curl -sS -X POST "https://kiste.run/v1/webhooks" \
  -H "Authorization: Bearer $KISTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"deploy-bot","url":"https://example.com/kiste-webhook","events":["instance.running","instance.stopped"]}'
```

**Request body:** [CreateWebhookRequest](https://docs.kiste.run/api/schemas.md#createwebhookrequest)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `events` | array of string | yes |  |
| `name` | string | yes |  |
| `url` | string | yes |  |

**Responses:**

- `200` OK. Body: [CreatedWebhookResponse](https://docs.kiste.run/api/schemas.md#createdwebhookresponse)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

## Get a webhook

`GET /v1/webhooks/{id}`

One endpoint with its events and delivery health.

**Path parameters:**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The object's ID. |

```bash
curl -sS "https://kiste.run/v1/webhooks/ID" \
  -H "Authorization: Bearer $KISTE_TOKEN"
```

**Responses:**

- `200` OK. Body: [WebhookEndpointResponse](https://docs.kiste.run/api/schemas.md#webhookendpointresponse)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

## Change a webhook

`PATCH /v1/webhooks/{id}`

Changes the name, URL, event types or whether the endpoint is enabled.

**Path parameters:**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The object's ID. |

```bash
curl -sS -X PATCH "https://kiste.run/v1/webhooks/ID" \
  -H "Authorization: Bearer $KISTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'
```

**Request body:** [UpdateWebhookRequest](https://docs.kiste.run/api/schemas.md#updatewebhookrequest)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | boolean or null | no |  |
| `events` | array of string or null | no |  |
| `name` | string or null | no |  |
| `url` | string or null | no |  |

**Responses:**

- `200` OK. Body: [WebhookEndpointResponse](https://docs.kiste.run/api/schemas.md#webhookendpointresponse)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

## Delete a webhook

`DELETE /v1/webhooks/{id}`

Deletes the endpoint; no further deliveries are made.

**Path parameters:**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The object's ID. |

```bash
curl -sS -X DELETE "https://kiste.run/v1/webhooks/ID" \
  -H "Authorization: Bearer $KISTE_TOKEN"
```

**Responses:**

- `200` OK. Body: [DeletedWebhookResponse](https://docs.kiste.run/api/schemas.md#deletedwebhookresponse)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

## Send a test delivery

`POST /v1/webhooks/{id}/test`

Sends a `webhook.test` delivery now and answers with the receiver's response.

**Path parameters:**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The object's ID. |

```bash
curl -sS -X POST "https://kiste.run/v1/webhooks/ID/test" \
  -H "Authorization: Bearer $KISTE_TOKEN"
```

**Responses:**

- `200` OK. Body: [WebhookDeliveryResponse](https://docs.kiste.run/api/schemas.md#webhookdeliveryresponse)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

## List deliveries

`GET /v1/webhooks/{id}/deliveries`

The last 50 deliveries of an endpoint, with attempt, state and HTTP status.

**Path parameters:**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The object's ID. |

```bash
curl -sS "https://kiste.run/v1/webhooks/ID/deliveries" \
  -H "Authorization: Bearer $KISTE_TOKEN"
```

**Responses:**

- `200` OK. Body: list of [WebhookDeliveryResponse](https://docs.kiste.run/api/schemas.md#webhookdeliveryresponse)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

## List alerts

`GET /v1/alerts`

Your account alerts, unacknowledged first.

```bash
curl -sS "https://kiste.run/v1/alerts" \
  -H "Authorization: Bearer $KISTE_TOKEN"
```

**Responses:**

- `200` OK. Body: list of [AlertResponse](https://docs.kiste.run/api/schemas.md#alertresponse)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

## Acknowledge an alert

`POST /v1/alerts/{id}/acknowledge`

Closes an alert. A new occurrence raises it again.

**Path parameters:**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The object's ID. |

```bash
curl -sS -X POST "https://kiste.run/v1/alerts/ID/acknowledge" \
  -H "Authorization: Bearer $KISTE_TOKEN"
```

**Responses:**

- `200` OK. Body: [AlertResponse](https://docs.kiste.run/api/schemas.md#alertresponse)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

## Get alert e-mail settings

`GET /v1/alerts/preferences`

Which alert kinds are sent to your e-mail address.

```bash
curl -sS "https://kiste.run/v1/alerts/preferences" \
  -H "Authorization: Bearer $KISTE_TOKEN"
```

**Responses:**

- `200` OK. Body: [AlertPreferencesResponse](https://docs.kiste.run/api/schemas.md#alertpreferencesresponse)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

## Change alert e-mail settings

`PATCH /v1/alerts/preferences`

Turns e-mail for single alert kinds on or off. Alerts stay visible in the console and as events either way.

```bash
curl -sS -X PATCH "https://kiste.run/v1/alerts/preferences" \
  -H "Authorization: Bearer $KISTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"disk_almost_full":false}'
```

**Request body:** map of boolean

**Responses:**

- `200` OK. Body: [AlertPreferencesResponse](https://docs.kiste.run/api/schemas.md#alertpreferencesresponse)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

## Related topics

- [Overview](https://docs.kiste.run/api.md)
- [Conventions](https://docs.kiste.run/api/conventions.md)
- [Kisten](https://docs.kiste.run/api/instances.md)
- [Commands](https://docs.kiste.run/api/commands.md)
- [Snapshots](https://docs.kiste.run/api/snapshots.md)
- [SSH and terminal](https://docs.kiste.run/api/ssh-and-terminal.md)
- [Desktop](https://docs.kiste.run/api/desktop.md)
- [Kiste Stream](https://docs.kiste.run/api/stream.md)
- [Images and environments](https://docs.kiste.run/api/images.md)
- [Account and access](https://docs.kiste.run/api/account.md)
- [Sign-in and platform](https://docs.kiste.run/api/platform.md)
- [Schemas](https://docs.kiste.run/api/schemas.md)
- Previous: [Images and environments](https://docs.kiste.run/api/images.md)
- Next: [Account and access](https://docs.kiste.run/api/account.md)