API keys and webhooks (for developers)

This guide is for developers who want to connect their own systems to havelo. If you just want to link havelo to another app without code, use Zapier instead.

Integrations are available on the Pro plan and above.

API keys

Every request is authenticated with a personal API key.

1. In havelo, open Settings and choose the Integrations tab.
2. Click Create API key and give it a name.
3. Copy the key immediately. It starts with hv_live_ and is shown only once.

Keep keys secret and out of version control. You can revoke a key at any time and it stops working instantly. Create a separate key per system, so you can revoke one without affecting the others.

Base URL

All endpoints live under https://api.havelo.co.uk/api/public/v1.

Authentication

Send your key on every request, either as a bearer token or an X-API-Key header:

Authorization: Bearer hv_live_your_key_here

For example, to confirm your key works:

curl https://api.havelo.co.uk/api/public/v1/me -H "Authorization: Bearer hv_live_your_key_here"

Endpoints

List endpoints return newest first, in the shape { "object": "list", "data": [ ... ] }. Every request is scoped to the account that owns the key, so you only ever see your own data.

Creating records

Send a JSON body. To create a property, include at least address_line_1, city and postcode. To create a tenant or a maintenance request, include a property_id you own.

Example (create a repair):

curl -X POST https://api.havelo.co.uk/api/public/v1/maintenance -H "Authorization: Bearer hv_live_your_key_here" -H "Content-Type: application/json" -d '{"property_id": 1, "title": "Leaking tap", "priority": "high"}'

Webhooks

Instead of polling, you can have havelo push events to your server the moment they happen.

1. In Settings, then Integrations, add a webhook endpoint (a public https URL on your server).
2. havelo sends a POST with a JSON body whenever a matching event fires.
3. You can send a test delivery from the same screen.

Events

• property.created
• tenant.created
• maintenance.created
• maintenance.updated
• maintenance.completed

Verifying a delivery

Each delivery includes these headers:

• X-Havelo-Event: the event type, for example maintenance.created.
• X-Havelo-Delivery: a unique id for the delivery.
• X-Havelo-Signature: a signature in the form sha256=<hex>.

The signature is an HMAC-SHA256 of the exact request body, using your endpoint's signing secret (it starts with whsec_ and is shown when you create the webhook). Recompute it on your side and compare, to be sure the request really came from havelo. Reject anything that does not match.

Notes

• All traffic is over HTTPS.
• Keep your API keys and webhook secrets private. Rotate them if they are ever exposed.
• Need a hand? Contact support.