API reference

Webhooks

Outgoing webhooks and the event feed.

Account event feed

GET/api/v1/accounts/{id}/events

GET /events?after=<seq>&type=a,b&limit=n — the outbox as a feed, for integrations that poll.

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: events
Feature: api_tokens
Operation: listEventsForAccount · ky call listEventsForAccount

Parameters

Name	In
`id`	path
`after`	query
`limit`	query
`type`	query

Responses

200 OK
Body
Field Type
items array of StoreEvent
next integer
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
500 Internal Server Error: internal

Field	Type
`items`	array of StoreEvent
`next`	integer

List the account's webhooks

GET/api/v1/accounts/{id}/webhooks

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: webhooks
Feature: api_tokens
Operation: listWebhooksForAccount · ky call listWebhooksForAccount

Parameters

Name	In
`id`	path

Responses

200 OK
Body
Field Type
items array of StoreWebhookEndpoint
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
500 Internal Server Error: internal

Field	Type
`items`	array of StoreWebhookEndpoint

Add an account webhook

POST/api/v1/accounts/{id}/webhooks

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: webhooks
Feature: api_tokens
Operation: createWebhookForAccount · ky call createWebhookForAccount

Parameters

Name	In
`id`	path

Request body

Field	Type
`description`	string
`enabled`	boolean
`events`	array of string
`url`	string

Responses

201 Created
Body
Field Type
secret string
webhook StoreWebhookEndpoint
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
409 Conflict: too-many
422 Unprocessable Entity: invalid-description, invalid-events, invalid-url
500 Internal Server Error: internal

Field	Type
`secret`	string
`webhook`	StoreWebhookEndpoint

Delete an account webhook

DELETE/api/v1/accounts/{id}/webhooks/{wid}

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: webhooks
Feature: api_tokens
Operation: deleteWebhookForAccount · ky call deleteWebhookForAccount

Parameters

Name	In
`id`	path
`wid`	path

Responses

204 Done, no content
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
500 Internal Server Error: internal

Get an account webhook

GET/api/v1/accounts/{id}/webhooks/{wid}

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: webhooks
Feature: api_tokens
Operation: getWebhookForAccount · ky call getWebhookForAccount

Parameters

Name	In
`id`	path
`wid`	path

Responses

200 OK

Body

Field	Type
`account_id`	string
`consecutive_failures` always	integer
`created_at` always	integer
`description` always	string
`disabled_reason`	string
`enabled` always	boolean
`events` always	array of string
`id` always	string
`owner_type` always	string
`updated_at` always	integer
`url` always	string

401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
500 Internal Server Error: internal

Update an account webhook

PATCH/api/v1/accounts/{id}/webhooks/{wid}

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: webhooks
Feature: api_tokens
Operation: updateWebhookForAccount · ky call updateWebhookForAccount

Parameters

Name	In
`id`	path
`wid`	path

Request body

Field	Type
`description`	string
`enabled`	boolean
`events`	array of string
`url`	string

Responses

200 OK

Body

Field	Type
`account_id`	string
`consecutive_failures` always	integer
`created_at` always	integer
`description` always	string
`disabled_reason`	string
`enabled` always	boolean
`events` always	array of string
`id` always	string
`owner_type` always	string
`updated_at` always	integer
`url` always	string

401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
422 Unprocessable Entity: invalid-description, invalid-events, invalid-url
500 Internal Server Error: internal

List an account webhook's deliveries

GET/api/v1/accounts/{id}/webhooks/{wid}/deliveries

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: webhooks
Feature: api_tokens
Operation: webhookDeliveriesForAccount · ky call webhookDeliveriesForAccount

Parameters

Name	In
`id`	path
`wid`	path
`limit`	query

Responses

200 OK
Body
Field Type
items array of StoreWebhookDelivery
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
500 Internal Server Error: internal

Field	Type
`items`	array of StoreWebhookDelivery

Redeliver an account webhook delivery

POST/api/v1/accounts/{id}/webhooks/{wid}/deliveries/{did}/redeliver

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: webhooks
Feature: api_tokens
Operation: redeliverWebhookForAccount · ky call redeliverWebhookForAccount

Parameters

Name	In
`id`	path
`wid`	path
`did`	path

Responses

202 Accepted (runs in the background)
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
500 Internal Server Error: internal

Rotate an account webhook's secret

POST/api/v1/accounts/{id}/webhooks/{wid}/rotate-secret

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: webhooks
Feature: api_tokens
Operation: rotateWebhookSecretForAccount · ky call rotateWebhookSecretForAccount

Parameters

Name	In
`id`	path
`wid`	path

Responses

200 OK
Body
Field Type
secret string
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
500 Internal Server Error: internal

Field	Type
`secret`	string

Send a test event to an account webhook

POST/api/v1/accounts/{id}/webhooks/{wid}/test

Queues a webhook.ping to this endpoint only, whatever its event list.

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: webhooks
Feature: api_tokens
Operation: testWebhookForAccount · ky call testWebhookForAccount

Parameters

Name	In
`id`	path
`wid`	path

Responses

202 Accepted (runs in the background)
Body
Field Type
event_id string
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
500 Internal Server Error: internal

Field	Type
`event_id`	string

Events an account webhook can receive

GET/api/v1/accounts/{id}/webhooks/events

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: webhooks
Feature: api_tokens
Operation: webhookCatalogForAccount · ky call webhookCatalogForAccount

Parameters

Name	In
`id`	path

Responses

200 OK
Body
Field Type
items array of WebhooksEventType
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)

Field	Type
`items`	array of WebhooksEventType

Server event feed

GET/api/v1/events

GET /events?after=<seq>&type=a,b&limit=n — the outbox as a feed, for integrations that poll.

Who: root
API tokens: admin token area: server
Operation: listEvents · ky call listEvents

Parameters

Name	In
`after`	query
`limit`	query
`type`	query

Responses

200 OK
Body
Field Type
items array of StoreEvent
next integer
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
500 Internal Server Error: internal

Field	Type
`items`	array of StoreEvent
`next`	integer

List server webhooks

GET/api/v1/webhooks

Who: root
API tokens: admin token area: server
Operation: listWebhooks · ky call listWebhooks

Responses

200 OK
Body
Field Type
items array of StoreWebhookEndpoint
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
500 Internal Server Error: internal

Field	Type
`items`	array of StoreWebhookEndpoint

Add a server webhook

POST/api/v1/webhooks

Who: root
API tokens: admin token area: server
Operation: createWebhook · ky call createWebhook

Request body

Field	Type
`description`	string
`enabled`	boolean
`events`	array of string
`url`	string

Responses

201 Created
Body
Field Type
secret string
webhook StoreWebhookEndpoint
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
409 Conflict: too-many
422 Unprocessable Entity: invalid-description, invalid-events, invalid-url
500 Internal Server Error: internal

Field	Type
`secret`	string
`webhook`	StoreWebhookEndpoint

Delete a server webhook

DELETE/api/v1/webhooks/{wid}

Who: root
API tokens: admin token area: server
Operation: deleteWebhook · ky call deleteWebhook

Parameters

Name	In
`wid`	path

Responses

204 Done, no content
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
500 Internal Server Error: internal

Get a server webhook

GET/api/v1/webhooks/{wid}

Who: root
API tokens: admin token area: server
Operation: getWebhook · ky call getWebhook

Parameters

Name	In
`wid`	path

Responses

200 OK

Body

Field	Type
`account_id`	string
`consecutive_failures` always	integer
`created_at` always	integer
`description` always	string
`disabled_reason`	string
`enabled` always	boolean
`events` always	array of string
`id` always	string
`owner_type` always	string
`updated_at` always	integer
`url` always	string

401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
500 Internal Server Error: internal

Update a server webhook

PATCH/api/v1/webhooks/{wid}

Who: root
API tokens: admin token area: server
Operation: updateWebhook · ky call updateWebhook

Parameters

Name	In
`wid`	path

Request body

Field	Type
`description`	string
`enabled`	boolean
`events`	array of string
`url`	string

Responses

200 OK

Body

Field	Type
`account_id`	string
`consecutive_failures` always	integer
`created_at` always	integer
`description` always	string
`disabled_reason`	string
`enabled` always	boolean
`events` always	array of string
`id` always	string
`owner_type` always	string
`updated_at` always	integer
`url` always	string

401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
422 Unprocessable Entity: invalid-description, invalid-events, invalid-url
500 Internal Server Error: internal

List a server webhook's deliveries

GET/api/v1/webhooks/{wid}/deliveries

Who: root
API tokens: admin token area: server
Operation: webhookDeliveries · ky call webhookDeliveries

Parameters

Name	In
`wid`	path
`limit`	query

Responses

200 OK
Body
Field Type
items array of StoreWebhookDelivery
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
500 Internal Server Error: internal

Field	Type
`items`	array of StoreWebhookDelivery

Redeliver a server webhook delivery

POST/api/v1/webhooks/{wid}/deliveries/{did}/redeliver

Who: root
API tokens: admin token area: server
Operation: redeliverWebhook · ky call redeliverWebhook

Parameters

Name	In
`wid`	path
`did`	path

Responses

202 Accepted (runs in the background)
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
500 Internal Server Error: internal

Rotate a server webhook's secret

POST/api/v1/webhooks/{wid}/rotate-secret

Who: root
API tokens: admin token area: server
Operation: rotateWebhookSecret · ky call rotateWebhookSecret

Parameters

Name	In
`wid`	path

Responses

200 OK
Body
Field Type
secret string
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
500 Internal Server Error: internal

Field	Type
`secret`	string

Send a test event to a server webhook

POST/api/v1/webhooks/{wid}/test

Queues a webhook.ping to this endpoint only, whatever its event list.

Who: root
API tokens: admin token area: server
Operation: testWebhook · ky call testWebhook

Parameters

Name	In
`wid`	path

Responses

202 Accepted (runs in the background)
Body
Field Type
event_id string
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
500 Internal Server Error: internal

Field	Type
`event_id`	string

Event catalog

GET/api/v1/webhooks/events

Who: root
API tokens: admin token area: server
Operation: webhookCatalog · ky call webhookCatalog

Responses

200 OK
Body
Field Type
items array of WebhooksEventType
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)

Webhooks

#Account event feed

Parameters

Responses

#List the account's webhooks

Parameters

Responses

#Add an account webhook

Parameters

Request body

Responses

#Delete an account webhook

Parameters

Responses

#Get an account webhook

Parameters

Responses

#Update an account webhook

Parameters

Request body

Responses

#List an account webhook's deliveries

Parameters

Responses

#Redeliver an account webhook delivery

Parameters

Responses

#Rotate an account webhook's secret

Parameters

Responses

#Send a test event to an account webhook

Parameters

Responses

#Events an account webhook can receive

Parameters

Responses

#Server event feed

Parameters

Responses

#List server webhooks

Responses

#Add a server webhook

Request body

Responses

#Delete a server webhook

Parameters

Responses

#Get a server webhook

Parameters

Responses

#Update a server webhook

Parameters

Request body

Responses

#List a server webhook's deliveries

Parameters

Responses

#Redeliver a server webhook delivery

Parameters

Responses

#Rotate a server webhook's secret

Parameters

Responses

#Send a test event to a server webhook

Parameters

Responses

#Event catalog

Responses

Account event feed

List the account's webhooks

Add an account webhook

Delete an account webhook

Get an account webhook

Update an account webhook

List an account webhook's deliveries

Redeliver an account webhook delivery

Rotate an account webhook's secret

Send a test event to an account webhook

Events an account webhook can receive

Server event feed

List server webhooks

Add a server webhook

Delete a server webhook

Get a server webhook

Update a server webhook

List a server webhook's deliveries

Redeliver a server webhook delivery

Rotate a server webhook's secret

Send a test event to a server webhook

Event catalog