Set up API keys and webhooks

May not be enabled

API & Webhooks may not be turned on for your workspace or plan. If you don't see it, contact your workspace admin.

API keys give an integration programmatic access to your account’s read APIs, and webhooks push event notifications to your own HTTPS endpoints. Together they let you connect Belrald Assets to the rest of your systems.

Everything lives in Settings → API & Webhooks, across two tabs: API keys and Webhooks. Owners and admins can create and manage both; managers see the page read-only, marked with a Read-only chip. If the feature is not turned on for your account, the page shows a card explaining that Public API isn’t enabled — contact your administrator to turn it on.

Create an API key

1. Open the API keys tab and select New API key.
2. Name — give the key a recognisable label, such as CI pipeline (120 characters or fewer).
3. Environment — choose Live or Test. This is set at creation and can’t be changed later.
4. Scopes — tick the permissions the key needs. Only read:workorders and read:assets map to a live endpoint today and are ticked by default. The other four scopes are badged no endpoint yet — you can grant them, but they do nothing until the public write API ships.
5. Select Create key.

Caution

The full secret is shown once, in the API key created dialog. Copy it straight away — Belrald Assets never stores it and can’t show it to you again. If you lose it, rotate the key for a new one.

The key then appears in the list showing its name, an environment pill, the masked key (prefix…last4 — never the full secret), its scopes and when it was last used (Never used until an integration calls the API with it).

Rotate or revoke a key

Open the ⋯ menu on a key’s row for its actions.

• Edit changes the key’s name and scopes. The environment stays fixed.
• Rotate generates a new secret, shown once. Your previous secret keeps working for 24 hours, so you can update your integration without downtime.
• Revoke disables the key. Any integration using it stops working immediately, and this can’t be undone — the button asks you to click again to confirm.

Create a webhook

1. Open the Webhooks tab and select New webhook.
2. Name — a recognisable label, such as Ops relay.
3. Endpoint URL — the destination for deliveries. It must be a public HTTPS URL.
4. Events — pick the events to subscribe to from the grouped, searchable list (Work orders, Assets, Maintenance requests, Preventive maintenance, Meters, Contracts, Inventory, Quotes, SLA, Certifications, Payments and Workflow). Select at least one.
5. Select Create webhook.

Caution

The signing secret (whsec_…) is shown once, in the Webhook created dialog. Copy it now — you won’t see it again. Use it to verify that deliveries really came from Belrald Assets.

The create dialog also carries a collapsible Verify deliveries recipe you can copy. The webhook then appears in the list with a state dot, its URL, an events count, the last delivery time with a success or failure marker, and a state pill of Active, Disabled or Paused.

Verify each delivery

Every delivery carries an X-Belrald-Signature header of the form t=<unix>,v1=<hmac_sha256_hex>. Before you trust a payload:

1. Read the timestamp t and signature v1 from the header.
2. Build the signed payload as {t}.{rawBody} — the timestamp, a dot, then the exact raw request body.
3. Compute hmac_sha256(signing_secret, signed_payload) and compare it against v1 using a constant-time comparison.

The request body is JSON of the shape { id, type, occurredAt, data }.

Manage and monitor a webhook

Open the ⋯ menu on a webhook’s row for its actions.

• Edit changes the name, URL and events, and — on an existing webhook — toggles it Active.
• Send test queues a synthetic test delivery. Check the delivery log to see the result; there is no inline response.
• Delivery log shows the 100 most recent deliveries, newest first. Each row gives the event type, the attempt count, an HTTP status, the response snippet and a status of pending, success, failed or exhausted. The log is read-only.
• Rotate secret issues a new signing secret, shown once.
• Enable / Disable turns deliveries on or off.
• Delete removes the webhook. It stops receiving events, and this can’t be undone.

Caution

Rotating the signing secret is an instant cutover — there is no grace period. The webhook breaks until you update your verifier with the new secret, so do it in the same sitting.

Note

Belrald Assets disables a webhook automatically after repeated delivery failures. A disabled webhook shows a recent failures note on its row; fix your endpoint, then Enable it again.