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

Belvak has its own app in the Zapier directory, so there is nothing to install and no key to copy. Search for Belvak in Zapier, click Connect, and approve the workspace you want to automate. The dedicated Zapier integration page walks through the same setup with screenshots.

Connecting your workspace

1. In Zapier, start a Zap and search for Belvak.
2. Choose a Belvak trigger, action, or search, then click Connect.
3. Sign in to Belvak in the window that opens and approve the workspace you want Zapier to use.
4. Zapier confirms the connection and names it after that workspace. No API key is involved.

What the Belvak app can do

Three triggers start a Zap when something happens in Belvak: New Client, New Invoice, and New Payment. Two actions write back into your workspace: Create Client and Create Invoice. A third step, Find Client, is a search that looks a client up by name or email so a Zap can check whether someone exists before it creates anything.

Disconnecting Zapier

Open Settings, go to the Integrations tab, and find the connected apps list. Disconnecting revokes Belvak access immediately and removes any webhooks Zapier created. The Zap itself stays where it is in Zapier, but it will fail until you reconnect it or point it at another connection.

Which plan you need

API access is a Professional plan feature, so the workspace you connect needs to be on Professional or higher. If your workspace is on Free, the approval step will tell you so and the connection will not complete until you upgrade. On Zapier's side, a free account is enough to build and run a two-step Zap.

Building a Zap without the Belvak app

The Belvak app covers the most common workflows. For anything it does not cover yet, the API and webhooks are still there: use Webhooks by Zapier with Catch Hook to start a Zap from any of the 33 Belvak events, and API by Zapier with an Authorization: Bearer bv_live_... header to reach any endpoint. Save the key as a stored Authorization header rather than typing it into a step, so teammates who can edit the Zap cannot read it. Both of those Zapier steps are part of Zapier's own paid plans.

If a Zap is not working

Zapier supports the Zaps you build, including the ones that use Belvak. If a Zap errors, stops firing, or does not connect, report it at zapier.com/app/get-help. Their team has the run history for your Zap and passes anything on our side straight to us.

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.