API and webhooks
Settings → API & webhooks is where your organisation mints REST API keys and configures the webhook that pushes events to your own system — see Webhooks for the full event catalogue and signature verification.
What it is
This section holds three cards: REST API — quick-start documentation, scope checkboxes and key minting; Webhook (push to your CMS) — your endpoint URL, the signing secret, and a live test-event sender; and, for a landlord organisation, a read-only summary pointing to the dedicated Contractors tab. It’s a Platform-plan feature.
Before you start
API keys and webhooks require the Platform plan and organisation-admin access to Settings, a level higher than most other Settings sections.
How to do it
- Open Settings → API & webhooks.
- To mint a key: enter a label, tick the scopes it needs (
surveys:read,properties:read,work-orders:read,work-orders:write,contractors:read,contractors:write), and click Mint key. The plaintext key is shown once — copy it before leaving the page. - To revoke a key, click Revoke next to it and confirm — any integration using it stops working immediately.
- To configure a webhook: enter your endpoint URL and click Save. The signing secret is shown once, and is regenerated every time you re-save the URL.
- Click Send test event to fire a real, signed
test.pingevent immediately — see Testing a connection for how to read the result.
How it integrates
A minted key can only ever use the scopes it was granted — a key scoped to surveys:read alone can never write a work order, whatever your own organisation-level permissions allow. Revoking a key or changing the webhook URL takes effect immediately, with no propagation delay. The full event catalogue, retry behaviour and signature verification are covered in Webhooks; the REST API’s resources, pagination and rate limits are documented at /developers/, linked directly from this screen.
Common problems
- The whole section shows an upgrade notice instead of the controls. API keys and webhooks are a Platform-plan feature — the rest of Settings works as normal below that tier.
- I lost the plaintext key shown after minting. It can’t be retrieved again — revoke it and mint a new one.
- My webhook stopped verifying after I re-saved the URL. Re-saving always mints a fresh signing secret — update your endpoint with the new one shown at that moment.