Webhooks
Overview
Webhooks let external systems receive real-time HTTP notifications when data changes in Kompass. For example, when a project is created, an invoice is updated, or a client is deleted. Use them to integrate Kompass with tools like Slack, Zapier, or your own services without polling the API.
Creating a webhook
Webhook subscriptions are managed in Kompass Admin or through the public API. Before Kompass sends any deliveries, webhooks must be enabled for the organization in Kompass Admin under Webhooks > Configurations.
From Kompass Admin
- Open /admin/webhooks/webhook/.
- Click Add Webhook.
- Give the webhook a Name.
- Set the URL, the HTTPS endpoint that should receive events.
- Select the Events you want to subscribe to from the list.
- Choose the Org that owns the webhook and its Owner.
- Save. Kompass generates a signing secret (it starts with
whsec_) automatically and shows it once in the confirmation message; copy it now and store it with your integration.

From the API
POST /api/webhooks/
Authorization: Bearer <your-token>
Content-Type: application/json
{
"name": "Example integration",
"url": "https://example.com/kompass-webhook",
"events": ["project.create", "project.update", "invoice.*"]
}
The API response does not include the signing secret. To get one, rotate the secret in Kompass Admin as described in Rotating the signing secret below.
Event types
Each event has the form resource.action . Resources are client , contact , diary , expense , invoice , leave , payment , project , quote_item , sales_order and supplier . Actions are create , update and delete . Use resource.* to subscribe to all actions on a resource.
Diary create and update events fire only for approved entries, and leave create, update and delete events only for approved requests, with one exception: deleting an unapproved diary entry emits diary.delete . For create and update, the action depends on whether the record already existed when it was saved, not on whether this is its first approval: approving an existing diary entry or leave request emits update , creating one that is already approved emits create , and later edits of an approved record are also update .
Choosing Sync now on a client, contact, project, invoice, supplier or expense also sends an update event for it, even though nothing changed. Sync now is offered on records that sync to at least one other integration that keeps a sync status. See Syncing records to your integrations.
The synthetic event test.webhook is delivered by the Send test webhook action and is useful for validating your endpoint without touching real data.
Delivery format
Kompass webhooks follow the Standard Webhooks specification. Every delivery is a POST request to the webhook URL with these headers:
Content-Type: application/jsonUser-Agent: Kompass-Webhook/2.0webhook-ida unique message ID. It stays the same when a delivery is retried, so use it to recognize a delivery you have already processed.webhook-timestampthe Unix time of this attempt, in whole secondswebhook-signaturethe signature, for examplev1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
The event type is in the body (type ).
The body is JSON with this shape:
{
"id": "evt_1704067200000_123",
"type": "project.update",
"resource": "project",
"action": "update",
"created": "2026-05-18T10:23:11Z",
"object": { ... full serialized project ... },
"changes": {
"name": {"new": "Acme Ltd", "old": "Acme"}
},
"metadata": {
"version": "1.1",
"org": {"id": 7, "name": "Acme LLC"},
"user": {"id": 42, "email": "[email protected]"},
"webhook": {"id": 5, "delivery_id": 789, "delivery_attempt": 1}
}
}
For *.update events the payload also includes a changes object with the previous and new value of each field that changed. It is reliable for the record's own fields; changes to nested related records may not appear. Create and delete events do not include it, and neither do update events sent by Sync now.
Verifying the signature
Always verify webhook-signature before processing a delivery. The signature covers the message ID, the timestamp and the body, so a delivery that has been altered or replayed later fails the check.
The simplest way is a Standard Webhooks library, available for most languages. Pass it your signing secret, the raw request body and the request headers:
Python (pip install standardwebhooks ):
from standardwebhooks.webhooks import Webhook
wh = Webhook("whsec_...")
event = wh.verify(raw_body, request.headers) # raises if invalid or too old
Node.js (npm install standardwebhooks ):
import { Webhook } from "standardwebhooks";
const wh = new Webhook("whsec_...");
const event = wh.verify(rawBody, request.headers); // throws if invalid or too old
To verify without a library:
- Take the raw request body exactly as received. Do not parse and re-encode the JSON.
- Join the
webhook-id, thewebhook-timestampand the body with periods:{webhook-id}.{webhook-timestamp}.{body}. - Remove the
whsec_prefix from your secret and base64-decode the rest. The result is the signing key. - Compute the HMAC-SHA256 of the joined content with that key and base64-encode it.
- Compare it, using a constant-time comparison, with the part after
v1,inwebhook-signature. The header can hold several space-separated signatures; accept the delivery if any of them matches. - Reject the delivery if
webhook-timestampis more than five minutes from your current time.
Python example:
import base64, hashlib, hmac, time
def verify(body, headers, secret, tolerance=300):
msg_id = headers["webhook-id"]
timestamp = headers["webhook-timestamp"]
if abs(time.time() - int(timestamp)) > tolerance:
return False
key = base64.b64decode(secret.removeprefix("whsec_"))
signed = f"{msg_id}.{timestamp}.".encode() + body
expected = base64.b64encode(
hmac.new(key, signed, hashlib.sha256).digest()
).decode()
return any(
hmac.compare_digest(sig.removeprefix("v1,"), expected)
for sig in headers["webhook-signature"].split(" ")
if sig.startswith("v1,")
)
Rotating the signing secret
To rotate a secret, select the webhook on the Webhooks list in Kompass Admin, choose one of these actions from the Actions menu, click Go, and copy the new secret from the confirmation message. It is shown only once.
- Rotate signing secret (old secret keeps working for 24 hours): use this for a planned change. For the next 24 hours every delivery carries two signatures in
webhook-signature, one made with the new secret and one with the old, so your integration keeps accepting deliveries while you switch it to the new secret. The confirmation message, and the Security section of the webhook's page in Kompass Admin, show when the old secret stops being used. Rotating again within the 24 hours ends the oldest secret immediately: only the two most recent secrets are used. - Rotate signing secret now (old secret stops working immediately): use this if the secret may have leaked. Deliveries are signed with the new secret only, so your integration rejects them until it uses the new secret.
Standard Webhooks libraries, and the manual check above, accept a delivery when any of its signatures matches, so the two-signature period needs no extra code.
Retries and reliability
- Success: any 2xx response code.
- Timeouts: 3 seconds to connect, 27 seconds to read.
- Retries: failed deliveries are retried with exponential backoff: 1 minute, doubling to a 6-hour cap, up to 20 retries over about three days. After the final attempt the delivery is marked failed, and a webhook that keeps failing for three days is disabled. An HTTP 410 Gone response is the exception: it disables the webhook immediately and stops retries.
- Redirects: not followed. Your endpoint must return a 2xx directly.
- Source IP addresses: deliveries come from fixed IP addresses for your Kompass site, so you can allow them through a firewall. They are listed in the webhook's
source_ipsfield in the API, and under Sent from in the Security section of the webhook's page in Kompass Admin. - Internal addresses: the webhook URL must point to a public address. A URL that names an internal host directly, such as
localhostor a private IP address, is rejected when the webhook is saved. Every delivery also checks the address the host name resolves to, and a delivery to a private, loopback, link-local or other internal address fails without retries. - Rate limit: a maximum of 120 new deliveries per rolling minute per organization. Excess events are dropped, not queued. Retries do not count toward the limit.
- Deduplication: a newer event of the same type for the same object replaces that webhook's delivery that is still waiting to be sent or retried, so you may receive fewer deliveries than there were database writes.
Testing your endpoint
In Kompass Admin, select the webhook on the Webhooks list and choose Send test webhook from the Actions menu, or call POST /api/webhooks/{id}/test/ . Kompass sends a test.webhook event to your URL using the same signature and headers as a real delivery.
Delivery history is available at GET /api/webhooks/{id}/deliveries/ and on the webhook's page in Kompass Admin. Each entry records the response code, the timestamps and any retry attempts.
Security
- Keep your signing secret confidential. Anyone with the secret can forge events. If it may have leaked, use Rotate signing secret now.
- Always use HTTPS for the target URL.
- Verify
webhook-signatureon every request, and reject deliveries whosewebhook-timestampis more than five minutes off. - Ignore a delivery whose
webhook-idyou have already processed.