API & Webhooks

Creating and managing API keys

An API key is what lets a script or an automation tool act as your workspace. API access is a Professional plan feature, so keys are available once your workspace is on Professional.

Where to find API keys

Open Settings, go to the Integrations tab, and find the API & Webhooks panel. Your keys and webhooks are both managed there.

Creating an API key

1. In the API & Webhooks panel, choose Create key.
2. Give it a label that says where it will be used, for example "Zapier" or "Reporting script".
3. Copy the key that appears and store it somewhere safe.

The key is shown once

Rotating and revoking a key

You can rotate or revoke a key at any time from the same panel. Both take effect immediately: a revoked or rotated key stops working on its very next request, so if a key is ever exposed you can shut it off at once. Rotating gives you a fresh key to paste into your tool while the old one dies.

Who can manage keys

Only an admin can create, rotate, or revoke keys, so managing them needs the workspace settings permission. Keys belong to the whole workspace rather than to one person, and removing or changing the role of the person who made a key does not switch the key off. If someone leaves, rotate the keys they set up. You can review roles in the roles and permissions guide.

Authenticating requests

The bearer header

Send your key on every request as a bearer token in the Authorization header:

Authorization: Bearer bv_live_...

Testing your connection

The quickest way to check a key works is to call the connection-test endpoint. It returns your workspace name, your plan, and details about the key. If it comes back with your workspace, the key is good.

GET https://app.belvak.com/api/v1/me

Ids match what you see in Belvak

Every id in the API is the same reference number you see in your workspace, the one shown as #N on a record. Related records are linked by these numbers too, for example an invoice carries the project_id of the project it belongs to.

Registering webhooks

A webhook is a URL that Belvak posts to whenever something you care about happens. You can register one from Settings or over the API.

Adding a webhook in Settings

1. In the API & Webhooks panel, choose Add webhook.
2. Paste the URL that should receive the events (from Zapier, Make, n8n, Pipedream, or your own server).
3. Pick the events you want, or subscribe to all of them.
4. Save, then copy the signing secret that appears.

Registering a webhook with the API

You can also create, list, update, and remove webhooks through the API instead of the settings screen. See the developer reference for the exact calls.

The signing secret is shown once

Choosing events

A webhook can listen for specific events or for everything. Start narrow, with just the events your workflow needs, and add more later. You can change the events, the URL, or disable a webhook whenever you like.

Verifying webhook signatures

Every delivery is signed with your webhook's secret, so your receiver can confirm it came from Belvak and was not tampered with. Automation tools like Zapier handle the delivery for you, but if you receive webhooks on your own server, verify the signature.

The signature header

Each delivery carries a Belvak-Signature header with a timestamp and a signature:

Belvak-Signature: t=1750000000,v1=<hex>

How to verify a delivery

1. Read the timestamp t and the exact raw body of the request, before any parsing.
2. Join them with a dot to make the string {t}.{rawBody}.
3. Compute an HMAC-SHA256 of that string using your webhook secret.
4. Compare your result to the v1 value using a constant-time comparison.
5. Reject the delivery if the timestamp is more than five minutes away from your own clock, which stops replays.

Always verify against the raw body exactly as received. Parsing the JSON and rebuilding it changes the bytes and breaks the signature.

A worked example

With these fixed inputs you should get exactly the signature below. Use it to confirm your verification code before going live:

secret     whsec_test_secret
timestamp  1750000000
raw body   {"event":"invoice.created"}

signed string:
1750000000.{"event":"invoice.created"}

HMAC-SHA256 (hex):
0556c1c4f94574349f40d02a3d8038ddf20d741c66fe42de885f695ff11fef86

Connecting Zapier

There is no Belvak app in the Zapier directory yet. You connect the two using Zapier's own building blocks: Webhooks by Zapier to start a Zap from a Belvak event, and API by Zapier to read or write your Belvak data. The dedicated Zapier integration page walks through the same setup with screenshots.

Triggering a Zap from a Belvak event

1. In Zapier, start a Zap and choose Webhooks by Zapier as the trigger, then Catch Hook.
2. Zapier gives you a custom webhook URL. Copy it.
3. In Belvak, add a webhook and paste that URL, then choose which events should fire the Zap.
4. Send a test event so Zapier can see the shape of the data, then finish building your Zap.

Reading and writing Belvak from a Zap

1. Add an API by Zapier action step.
2. Point it at the Belvak endpoint you need, for example to create a client or raise an invoice.
3. Add your API key as an Authorization header, Bearer bv_live_....
4. Map fields from your trigger into the request, and test the step.

Keeping your API key private

Save your key as a stored Authorization header on the API by Zapier step, where other people editing the Zap cannot read it. The Custom Request action works too, but anything you type into it is visible to everyone who can edit that Zap, so prefer the stored header. You can always rotate the key from Settings if you need to.

Which plan you need

On the Belvak side, API keys and webhooks are a Professional plan feature. On the Zapier side, the Webhooks by Zapier and API by Zapier steps are part of Zapier's own paid plans, so you will need a Zapier plan that includes them.

Connecting Make, n8n, and Pipedream

Any tool that can receive a webhook and make an HTTP request can work with Belvak today. The pattern is always the same: use the tool's webhook trigger to catch Belvak events, and its HTTP request step to call the Belvak API with your key. Here is how that looks in three popular tools.

Make

1. Add a Webhooks module and choose Custom webhook as the trigger. Make gives you a URL.
2. Register that URL as a Belvak webhook and pick your events.
3. To write back, add an HTTP module, Make a request, pointed at the Belvak endpoint with an Authorization: Bearer header.

n8n

1. Add a Webhook trigger node and copy its production URL.
2. Register that URL as a Belvak webhook and pick your events.
3. To write back, add an HTTP Request node with header authentication, sending Authorization: Bearer bv_live_... to the Belvak endpoint.

Pipedream

1. Start a workflow with an HTTP / Webhook trigger and copy the endpoint URL.
2. Register that URL as a Belvak webhook and pick your events.
3. To write back, add an HTTP request step and send your Belvak call with an Authorization: Bearer header.

Webhook events reference

The 33 events

There are 33 events in total: a created, updated, and deleted event for each of the eleven record types you can work with:

• client, project, invoice, payment, proposal
• supplier, purchase, employee, maintenance
• referral, note

So the event names read like invoice.created, payment.created, or client.updated. These mirror the same changes your notifications and activity log already track.

What each delivery contains

Deliveries are deliberately small. Each one tells you the event name, when it happened, the workspace it came from, and the public id of the record, plus, for most events, a link to read the full record from the API. Deleted events and note events do not carry that link: a deleted record is gone, and notes are read as a list on their parent record. You hydrate the details with a normal API call when you need them. One thing to know: when an invoice's status flips because a payment arrived, that does not send an invoice.updated event. Read the invoice again after the payment.created event instead.

Duplicates and tombstones

Belvak aims to deliver every event at least once, which means a delivery can occasionally arrive more than once. Each delivery carries a unique id in the Belvak-Delivery header, so treat that id as seen and ignore repeats. If a delivery fails, Belvak retries it automatically with a growing delay, and a webhook that keeps failing is switched off for you until you fix and re-enable it.

A deleted event is a tombstone: it carries the public id of the record that was removed so you can mirror the deletion, but it has no link to read the record back, because it is gone.