Events, webhooks and 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.

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

Responses:

200 OK. Body: WatchEventsResponse

Errors use the error envelope.

List webhooks

GET /v1/webhooks

Your webhook endpoints.

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

Responses:

200 OK. Body: list of WebhookEndpointResponse

Errors use the error envelope.

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.

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

Field	Type	Required
`events`	array of string	yes
`name`	string	yes
`url`	string	yes

Responses:

200 OK. Body: CreatedWebhookResponse

Errors use the error envelope.

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.

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

Responses:

200 OK. Body: WebhookEndpointResponse

Errors use the error envelope.

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.

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

Field	Type	Required
`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

Errors use the error envelope.

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.

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

Responses:

200 OK. Body: DeletedWebhookResponse

Errors use the error envelope.

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.

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

Responses:

200 OK. Body: WebhookDeliveryResponse

Errors use the error envelope.

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.

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

Responses:

200 OK. Body: list of WebhookDeliveryResponse

Errors use the error envelope.

List alerts

GET /v1/alerts

Your account alerts, unacknowledged first.

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

Responses:

200 OK. Body: list of AlertResponse

Errors use the error envelope.

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.

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

Responses:

200 OK. Body: AlertResponse

Errors use the error envelope.

Get alert e-mail settings

GET /v1/alerts/preferences

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

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

Responses:

200 OK. Body: AlertPreferencesResponse

Errors use the error envelope.

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.

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

Errors use the error envelope.

Events, webhooks and alerts

On this page