Skip to content

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-timestamp is 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 2xx within 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-After in a 429 or 503 response is honoured when it is longer than the schedule.
  • A 410 Gone response 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-id is the same across retries and manual resends: store the IDs you processed and answer a repeat with just a 2xx.
  • Order is not guaranteed. Because of retries a later event can arrive first. If you need order, look at timestamp or 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-timestamp and 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.