Webhooks
Receiving events at your own address: signature verification, retries, deduplication.
Developer documentation
A webhook sends a signed POST request to your HTTPS address when an event happens in your account (an employee was added, a leave was approved). Event types and payload fields are in the Event catalogue.
Creating an endpoint
The account owner presses New endpoint on the Settings › API › Webhook screen, enters the address and a description, picks the event types and confirms with Create endpoint. Creating an endpoint asks for extra verification.
- The address starts with
https://and uses port 443. IP addresses, user information and internal network names are not accepted; every address the name resolves to must be on the public internet. This check is repeated on every delivery. - An endpoint receives the events of the modules its creator can see, within the creator's binding (the whole account or one company). If the creator's permissions narrow, the endpoint stops receiving the affected events.
- The signing secret starts with
whsec_and is shown only once. - An endpoint is not edited: to change the address or the events, delete the endpoint and create it again.
The request
POST /your/path HTTP/1.1
Content-Type: application/json
webhook-id: 2d8f6a4e-91b3-4c7d-8e5f-0a1b2c3d4e5f
webhook-timestamp: 1781597100
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
Body:
{
"id": "6f5e4d3c-2b1a-4c9d-8e7f-6a5b4c3d2e1f",
"type": "employee.created",
"timestamp": "2026-06-16T08:05:00.412Z",
"sequence": 4182,
"company_id": "0b8f6c1e-5f0a-4c7e-9a43-2f6f3a1d9c10",
"subject": {
"type": "employee",
"id": "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
},
"data": {
"employee_id": "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"org_unit_id": "c4a1e2b3-7d6f-4e5a-9b8c-1f2e3d4c5b6a",
"status": "active",
"hire_date": "2026-06-16"
}
}
id: the ID of the event.type: the event type.timestamp: when the event happened (UTC).sequence: a sequence number that increases within the account. It does not guarantee order (see below).company_id: the company of the event.subject: the type and ID of the record the event is about.data: the thin payload of the type. It carries IDs, statuses and days; it carries no names, free text, amounts, national IDs, IBANs or health information. Read the details from the API with your own scopes.
Verifying the signature
The signature follows the Standard Webhooks specification: the webhook-signature value is v1, followed by the base64 HMAC-SHA256 signature of the text webhook-id.webhook-timestamp.body. The key is the decoded bytes of the base64 after the whsec_ prefix of the secret.
When verifying:
- Use the raw body: parsing the JSON and writing it again changes the bytes and the signature no longer matches.
- Reject the request if
webhook-timestampis more than 5 minutes older or newer than the current time (replay protection). - Compare in constant time.
- The header can carry several space-separated signatures (while a secret is rotated); the request is valid if one matches.
Node.js
import { createHmac, timingSafeEqual } from 'node:crypto';
const TOLERANCE_SECONDS = 5 * 60;
/** headers: lowercase header names; rawBody: the raw body (Buffer or string). */
export function verifyWebhook(secret, headers, rawBody, now = Date.now()) {
const id = headers['webhook-id'];
const timestamp = headers['webhook-timestamp'];
const signatures = headers['webhook-signature'];
if (!id || !timestamp || !signatures || !/^\d{1,12}$/.test(timestamp)) return false;
if (Math.abs(Math.floor(now / 1000) - Number(timestamp)) > TOLERANCE_SECONDS) return false;
const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
const expected = createHmac('sha256', key).update(`${id}.${timestamp}.`).update(rawBody).digest();
return signatures.split(' ').some((entry) => {
const [version, value] = entry.split(',');
if (version !== 'v1' || !value) return false;
const given = Buffer.from(value, 'base64');
return given.length === expected.length && timingSafeEqual(given, expected);
});
}
Using it in an HTTP server:
import { createServer } from 'node:http';
import { verifyWebhook } from './verify-webhook.mjs';
const secret = process.env.BIIK_WEBHOOK_SECRET;
createServer((req, res) => {
const chunks = [];
req.on('data', (chunk) => chunks.push(chunk));
req.on('end', () => {
const rawBody = Buffer.concat(chunks);
if (!verifyWebhook(secret, req.headers, rawBody)) {
res.writeHead(400).end();
return;
}
// If this webhook-id was already processed, just return 2xx.
const event = JSON.parse(rawBody.toString('utf8'));
console.log(req.headers['webhook-id'], event.type);
res.writeHead(204).end();
});
}).listen(8080);
Python
import base64
import binascii
import hashlib
import hmac
import re
import time
TOLERANCE_SECONDS = 5 * 60
def verify_webhook(secret, headers, raw_body, now=None):
"""headers: lowercase header names; raw_body: the raw body (bytes)."""
msg_id = headers.get("webhook-id")
timestamp = headers.get("webhook-timestamp")
signatures = headers.get("webhook-signature")
if not msg_id or not timestamp or not signatures:
return False
if not re.fullmatch(r"[0-9]{1,12}", timestamp):
return False
current = time.time() if now is None else now
if abs(int(current) - int(timestamp)) > TOLERANCE_SECONDS:
return False
key = base64.b64decode(secret.removeprefix("whsec_"))
signed = msg_id.encode() + b"." + timestamp.encode() + b"." + raw_body
expected = hmac.new(key, signed, hashlib.sha256).digest()
for entry in signatures.split(" "):
version, _, value = entry.partition(",")
if version != "v1":
continue
try:
given = base64.b64decode(value, validate=True)
except (binascii.Error, ValueError):
continue
if hmac.compare_digest(given, expected):
return True
return False
Both examples are tested on every build against a reference signature and against real deliveries: a changed byte and a timestamp older than 5 minutes are rejected.
Response and retries
- Acknowledge the request with a
2xxwithin 15 seconds. Queue long work and answer right away. An endpoint that times out 3 times in a row gets 5 seconds until its next successful delivery. - Every response other than
2xx, and a timeout, counts as a failure. Redirects (3xx) are not followed and count as failures. - An event is attempted at most 10 times. The waits between attempts: immediately, 5 s, 5 min, 30 min, 2 h, 5 h, 10 h, 14 h, 20 h, 24 h. The waits are lengthened slightly at random. A
Retry-Afterin a429or503response is honoured when it is longer than the schedule. - A
410 Goneresponse turns the endpoint off. An endpoint that fails without interruption for 5 days is turned off too; in both cases the account owners are notified. - The delivery log is kept on screen for 30 days. You can resend a finished delivery from the screen; it goes out with the same
webhook-id.
Deduplication and order
- The same delivery can arrive more than once (for example when your response is lost on the way).
webhook-idis the same across retries and manual resends: store the IDs you processed and answer a repeat with just a2xx. - Order is not guaranteed. Because of retries a later event can arrive first. If you need order, look at
timestampor read the current state of the record from the API. - The body is produced once: every attempt of the same delivery sends the same bytes; only
webhook-timestampand the signature are renewed.
Rotating the secret
Rotate secret on the screen gives a new secret. During the overlap (24 hours by default, at most 7 days) every delivery carries two signatures: first with the new secret, then with the old one. If your verification code tries both secrets there is no interruption.
Test event
Send test event on the endpoint card sends a webhook.ping event to that endpoint only. Use it to check that your address and your signature verification work.
Limits
At most 10 endpoints per account and at most 10 custom headers per endpoint. The body is at most 256 KiB. Only the first 512 bytes of the receiver's response are kept in the delivery log.