Browse the docsREST API

REST API

The REST API is what Zapier, Make, n8n and your own code call to read your account's events and to subscribe to them. It speaks JSON over HTTPS and every request carries an API key.

10 min

On this page

Overview
Authentication
Errors
Rate limits
Endpoints
REST hooks for integrations
What now?

Overview

Every endpoint lives under the base URL below, followed by the version, for example /v1/me.

The samples on this page read the base URL from KADENS_API_URL and your key from KADENS_API_KEY, so you can paste them as they are.

Requests and responses are JSON. Send Content-Type: application/json with every request that has a body.

The version is part of the path. Each event also carries the version of its format in its version field, currently 2026-10-01, so your code can tell which shape it received.

Authentication

Every request needs an API key in the Authorization header as a Bearer token. Each endpoint lists the scope it needs.

API keys and scopes

Errors

Errors use standard HTTP status codes and a JSON body with the status, a message, the path and a request id you can quote to support.

Status	Meaning
`400`	The query or body did not pass validation. Check the fields against this reference.
`401`	The key is missing, badly formatted, revoked or expired.
`403`	The key is valid but lacks the scope this endpoint needs.
`429`	Too many requests. Wait for the time in the Retry-After header, then try again.

Error response

1
2
3
4
5
6
7
{
  "statusCode": 401,
  "message": "Missing or invalid API key",
  "timestamp": "2026-10-01T10:00:00.000Z",
  "path": "/api/v1/events",
  "requestId": "req_7c1e0b"
}

Rate limits

Limits are counted per API key. Going over any of them returns 429 until the window resets.

Window	Limit
`Per second`	40 requests
`Per 10 seconds`	250 requests
`Per minute`	800 requests

Handling a 429

Read the Retry-After header, wait that many seconds and retry. The body carries errorCode: RATE_LIMITED so your code does not have to parse the message.

Endpoints

GET/v1/me

Tests the key: returns the account it belongs to and its scopes. Works with any valid key.

Bash

1
2
curl "$KADENS_API_URL/v1/me" \
  -H "Authorization: Bearer $KADENS_API_KEY"

Sample response

1
2
3
4
5
6
7
8
9
10
11
{
  "entity": {
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "name": "Barcelona Salsa Studio"
  },
  "apiKeyId": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
  "scopes": [
    "webhooks.read",
    "webhooks.write"
  ]
}

GET/v1/event-typesScope: webhooks.read

Lists every event type you can subscribe to, with a sample of each and the fields that hold personal data.

Bash

1
2
curl "$KADENS_API_URL/v1/event-types" \
  -H "Authorization: Bearer $KADENS_API_KEY"

Sample response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
{
  "apiVersion": "2026-10-01",
  "data": [
    {
      "type": "order.paid",
      "family": "orders",
      "descriptionKey": "Webhooks.events.order_paid",
      "sample": {
        "order": {
          "id": "ord_91ac04",
          "status": "paid",
          "created_at": "2026-10-01T09:58:02Z",
          "paid_at": "2026-10-01T10:00:00Z",
          "event": {
            "id": "evt_7f3c2a",
            "name": "Salsa Congress Barcelona 2026"
          },
          "totals": {
            "gross": {
              "amount": 12000,
              "currency": "EUR"
            },
            "fees": {
              "amount": 600,
              "currency": "EUR"
            },
            "net": {
              "amount": 11400,
              "currency": "EUR"
            },
            "tax": {
              "amount": 2083,
              "currency": "EUR"
            }
          },
          "buyer": {
            "entity_id": "ent_5b21",
            "name": "Lucia Martin",
            "email": "lucia@example.com"
          },
          "lines": [
            {
              "ticket_type_id": "tt_full_pass",
              "name": "Full pass",
              "quantity": 1,
              "unit_price": {
                "amount": 12000,
                "currency": "EUR"
              }
            }
          ]
        }
      },
      "personalDataPaths": [
        "order.buyer.name",
        "order.buyer.email"
      ]
    }
  ]
}

GET/v1/eventsScope: webhooks.read

Lists recent events, newest first, in the same envelope as webhook deliveries. Integrations use it to show sample data.

Bash

1
2
curl "$KADENS_API_URL/v1/events?type=order.paid&limit=10" \
  -H "Authorization: Bearer $KADENS_API_KEY"

Sample response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
{
  "data": [
    {
      "id": "msg_2f8a1c7e",
      "type": "order.paid",
      "version": "2026-10-01",
      "occurred_at": "2026-10-01T10:00:00Z",
      "account": {
        "id": "ent_1a0f",
        "name": "Barcelona Salsa Studio"
      },
      "subject": {
        "type": "order",
        "id": "ord_91ac04",
        "sequence": 2
      },
      "correlation_id": null,
      "livemode": true,
      "data": {
        "order": {
          "id": "ord_91ac04",
          "status": "paid",
          "created_at": "2026-10-01T09:58:02Z",
          "paid_at": "2026-10-01T10:00:00Z",
          "event": {
            "id": "evt_7f3c2a",
            "name": "Salsa Congress Barcelona 2026"
          },
          "totals": {
            "gross": {
              "amount": 12000,
              "currency": "EUR"
            },
            "fees": {
              "amount": 600,
              "currency": "EUR"
            },
            "net": {
              "amount": 11400,
              "currency": "EUR"
            },
            "tax": {
              "amount": 2083,
              "currency": "EUR"
            }
          },
          "buyer": {
            "entity_id": "ent_5b21"
          },
          "lines": [
            {
              "ticket_type_id": "tt_full_pass",
              "name": "Full pass",
              "quantity": 1,
              "unit_price": {
                "amount": 12000,
                "currency": "EUR"
              }
            }
          ]
        }
      }
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

Parameter	Type	Description
`type`	string	Only events of this type.
`limit`	integer	How many events to return, from 1 to 100. Defaults to 25.
`cursor`	string	The nextCursor of the previous page, to read the next one.

Personal data is hidden by default

Names, emails and other personal fields are removed from events unless the key also holds the people.read scope.

POST/v1/webhooks/subscriptionsScope: webhooks.write

Creates an endpoint managed by the integration. It appears read-only in the dashboard. Returns 201 when it creates the subscription, and 200 with the existing one when the same subscription already exists.

Bash

1
2
3
4
curl -X POST "$KADENS_API_URL/v1/webhooks/subscriptions" \
  -H "Authorization: Bearer $KADENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"targetUrl":"https://hooks.example.com/kadens","eventTypes":["order.paid","attendee.checked_in"],"integration":"zapier","externalRef":"zap_812734"}'

Sample response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "id": "3d9f2b71-8c4e-4a6f-9b1d-5e7a0c2f8d14",
  "created": true,
  "targetUrl": "https://hooks.example.com/kadens",
  "eventTypes": [
    "order.paid",
    "attendee.checked_in"
  ],
  "integration": "zapier",
  "externalRef": "zap_812734",
  "apiVersion": "2026-10-01",
  "secret": "whsec_Zk3v9QmT1rX8bLp2Wc6yHn4s",
  "createdAt": "2026-10-01T10:00:00.000Z"
}

Field	Type	Description
`targetUrl`Required	string	The HTTPS address Kadens delivers events to.
`eventTypes`Required	string[]	The event types to deliver, from 1 to 50. Read the list from /v1/event-types.
`integration`Required	string	Who manages the subscription: zapier, make, n8n or other.
`externalRef`	string	Your own id for this subscription, up to 255 characters.

DELETE/v1/webhooks/subscriptions/:idScope: webhooks.write

Removes an endpoint the integration created. Returns 204 with no body.

Bash

1
2
curl -X DELETE "$KADENS_API_URL/v1/webhooks/subscriptions/3d9f2b71-8c4e-4a6f-9b1d-5e7a0c2f8d14" \
  -H "Authorization: Bearer $KADENS_API_KEY"

REST hooks for integrations

Automation tools connect to Kadens with the REST hooks pattern: they subscribe when a workflow is turned on and unsubscribe when it is turned off.

Subscribe
The tool calls POST /v1/webhooks/subscriptions with the address to deliver to and the event types it wants. Keep the id and the signing secret from the response.
Receive events
Kadens sends each matching event to that address as a signed POST. Verify the signature with the secret before trusting the payload.
Unsubscribe
When the workflow is turned off, the tool calls DELETE /v1/webhooks/subscriptions/:id with the id it kept.

Subscriptions created this way appear read-only in your dashboard, marked with the integration that manages them.

How to verify signatures

What now?

Open in dashboard

Was this helpful?

Can't find what you're looking for?Search againTalk to us

Status

Meaning

400

The query or body did not pass validation. Check the fields against this reference.

401

The key is missing, badly formatted, revoked or expired.

403

The key is valid but lacks the scope this endpoint needs.

429

Too many requests. Wait for the time in the Retry-After header, then try again.

Window

Limit

Per second

40 requests

Per 10 seconds

250 requests

Per minute

800 requests

{ "entity": { "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f", "name": "Barcelona Salsa Studio" }, "apiKeyId": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d", "scopes": [ "webhooks.read", "webhooks.write" ] }

{ "apiVersion": "2026-10-01", "data": [ { "type": "order.paid", "family": "orders", "descriptionKey": "Webhooks.events.order_paid", "sample": { "order": { "id": "ord_91ac04", "status": "paid", "created_at": "2026-10-01T09:58:02Z", "paid_at": "2026-10-01T10:00:00Z", "event": { "id": "evt_7f3c2a", "name": "Salsa Congress Barcelona 2026" }, "totals": { "gross": { "amount": 12000, "currency": "EUR" }, "fees": { "amount": 600, "currency": "EUR" }, "net": { "amount": 11400, "currency": "EUR" }, "tax": { "amount": 2083, "currency": "EUR" } }, "buyer": { "entity_id": "ent_5b21", "name": "Lucia Martin", "email": "lucia@example.com" }, "lines": [ { "ticket_type_id": "tt_full_pass", "name": "Full pass", "quantity": 1, "unit_price": { "amount": 12000, "currency": "EUR" } } ] } }, "personalDataPaths": [ "order.buyer.name", "order.buyer.email" ] } ] }

{ "data": [ { "id": "msg_2f8a1c7e", "type": "order.paid", "version": "2026-10-01", "occurred_at": "2026-10-01T10:00:00Z", "account": { "id": "ent_1a0f", "name": "Barcelona Salsa Studio" }, "subject": { "type": "order", "id": "ord_91ac04", "sequence": 2 }, "correlation_id": null, "livemode": true, "data": { "order": { "id": "ord_91ac04", "status": "paid", "created_at": "2026-10-01T09:58:02Z", "paid_at": "2026-10-01T10:00:00Z", "event": { "id": "evt_7f3c2a", "name": "Salsa Congress Barcelona 2026" }, "totals": { "gross": { "amount": 12000, "currency": "EUR" }, "fees": { "amount": 600, "currency": "EUR" }, "net": { "amount": 11400, "currency": "EUR" }, "tax": { "amount": 2083, "currency": "EUR" } }, "buyer": { "entity_id": "ent_5b21" }, "lines": [ { "ticket_type_id": "tt_full_pass", "name": "Full pass", "quantity": 1, "unit_price": { "amount": 12000, "currency": "EUR" } } ] } } } ], "nextCursor": null, "hasMore": false }

Parameter

Type

Description

type

string

Only events of this type.

limit

integer

How many events to return, from 1 to 100. Defaults to 25.

cursor

string

The nextCursor of the previous page, to read the next one.

curl -X POST "$KADENS_API_URL/v1/webhooks/subscriptions" \ -H "Authorization: Bearer $KADENS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"targetUrl":"https://hooks.example.com/kadens","eventTypes":["order.paid","attendee.checked_in"],"integration":"zapier","externalRef":"zap_812734"}'

{ "id": "3d9f2b71-8c4e-4a6f-9b1d-5e7a0c2f8d14", "created": true, "targetUrl": "https://hooks.example.com/kadens", "eventTypes": [ "order.paid", "attendee.checked_in" ], "integration": "zapier", "externalRef": "zap_812734", "apiVersion": "2026-10-01", "secret": "whsec_Zk3v9QmT1rX8bLp2Wc6yHn4s", "createdAt": "2026-10-01T10:00:00.000Z" }

Field

Type

Description

targetUrlRequired

string

The HTTPS address Kadens delivers events to.

eventTypesRequired

string[]

The event types to deliver, from 1 to 50. Read the list from /v1/event-types.

integrationRequired

string

Who manages the subscription: zapier, make, n8n or other.

externalRef

string

Your own id for this subscription, up to 255 characters.

Handling a 429

Personal data is hidden by default

Subscribe

Receive events

Unsubscribe

What now?

Handling a 429

Personal data is hidden by default

Subscribe

Receive events

Unsubscribe

What now?