Skip to main content
ClubHelix
Browse the guide

System & settings

API & webhooks

Read your club’s data over a REST API and receive signed webhook notifications.

API & webhooks lets your club's data flow into your own tools. Create a read-only API key to pull members, membership types, events, orders and check-ins into a spreadsheet, reporting dashboard or custom app — and add webhook endpoints so your systems hear about new members, paid orders and check-ins the moment they happen. You'll find it in the admin sidebar under System → API & webhooks.

Who can use this

You need to be a full admin for the organisation — moderators can't see this page, and it can't be granted through a council position or permission override. API keys give tenant-wide read access and webhook endpoints receive member data, so both stay with admins only.

The API and webhooks are a Pro plan feature (Enterprise included). On other plans the page shows an upgrade prompt instead.

What's on the page

  • API keys — create named keys, see when each was created and last used, and revoke any key instantly.
  • Webhook endpoints — add HTTPS URLs we should notify, choose which events each receives, pause/resume, send a test event, or delete an endpoint. Each endpoint has its own signing secret, shown on the page.
  • Recent deliveries — the last 20 webhook deliveries with their event, status, attempt count and time queued.

Step by step

Create an API key and make your first request

  1. Under API keys, give the key a name that says where it will be used (e.g. Reporting spreadsheet) and click Create key.
  2. Copy the full key from the green banner straight away — for security we only store a fingerprint, so the key is shown this once and never again.
  3. Call any endpoint with the key in the Authorization header:
curl -H "Authorization: Bearer chk_..." https://clubhelix.com/api/v1/members
  1. Available endpoints (all GET, JSON, paginated with ?limit= up to 100 and ?offset=):
    • /api/v1/members — your roster (status, joined date, paid-until, name and email)
    • /api/v1/membership-types — your active membership types
    • /api/v1/events — published events (add ?upcoming=true for future ones only)
    • /api/v1/orders — membership, shop and ticket orders summarised, newest first
    • /api/v1/checkins — attendance records

Add a webhook endpoint

  1. Under Webhook endpoints, enter the HTTPS URL your system listens on.
  2. Tick the events you want delivered — or leave every box unticked to receive all of them.
  3. Click Add endpoint. Note the signing secret shown on the endpoint's card — your receiver uses it to verify deliveries.
  4. Click Send test event to queue a test.ping delivery, then watch it arrive in Recent deliveries (deliveries go out every few minutes; failures retry up to 5 times).

Verify a webhook signature

Every delivery is a JSON POST with two headers: X-ClubHelix-Event (the event type) and X-ClubHelix-Signature (a hex HMAC-SHA256 of the raw request body, keyed with your endpoint's secret). Verify like this:

expected = hmac_sha256_hex(secret, raw_request_body)
if not constant_time_equals(expected, header["X-ClubHelix-Signature"]):
    reject the request

Always compute the HMAC over the raw bytes of the body, before any JSON parsing.

Revoke or rotate a key

  1. Click Revoke next to the key — it stops working immediately.
  2. To rotate, create a new key first, switch your integration over, then revoke the old one.

Field reference

Webhook event types:

EventFires when
member.createdA membership application is approved
member.updatedA member's payment status or paid-until date changes
membership_order.paidAn online membership purchase or renewal is paid
donation.paidA donation payment succeeds
shop_order.paidA shop order is paid
checkin.createdA member checks in (staff list, QR or kiosk)

Delivery payloads all share one shape: { "event": "...", "tenant_id": "...", "data": { ... }, "created_at": "..." }, where data is a small snapshot of the record (ids, status, amounts — you can fetch fuller details from the API using the ids).

Tips & FAQ

The key I created has disappeared — where do I find it? You can't: the full key is shown once at creation and only a fingerprint is stored. Create a new key and revoke the old one.

Why am I getting 403 responses? The API needs the Pro or Enterprise plan. If your club has moved to a lower plan, existing keys stop working until you upgrade again.

Why am I getting 429 responses? Each key is limited to 120 requests per minute. Slow your requests down or spread them out — the Retry-After header says how long to wait.

Can the API change or delete data? No. Version 1 keys are strictly read-only, and every key is scoped to your organisation only.

A delivery shows as Failed — will it retry? Each delivery retries up to 5 times. After the fifth failure it stops; fix your endpoint and use Send test event to confirm it's healthy again.

API & webhooks — ClubHelix Help