Webhooks
Get JaKun changes pushed to your URL: event types, payload, signature check, retries with backoff, test events and the delivery log.
A webhook subscription sends a signed POST to your URL when something changes in
JaKun. Events are written in the same transaction as the change and delivered by a background
worker, so a slow receiver never slows JaKun down and nothing is lost if it is down.
Subscribe#
In Indstillinger → Webhooks press New webhook: a name, an https:// URL and
optionally which events and objects. The signing secret is shown once. Press Send test
to get a webhook.test event right away and see your server's answer.
The URL must be public https://. Addresses that resolve to private,
loopback or link-local networks are refused when you save and again before every delivery.
Event types#
| type | When |
|---|---|
record.created, record.updated, record.deleted, record.restored | Any record of any object. |
record.stage_changed, record.status_changed, record.owner_changed, record.tag_changed | Semantic changes, sent in addition to record.updated. |
record.merged | Duplicate merged into another record. |
form.submitted | Public form sent. |
webhook.test | Only from Send test; contains no customer data. |
Payload#
POST /your/endpoint
Content-Type: application/json
User-Agent: JaKun-Webhooks/1
X-Jakun-Event: record.stage_changed
X-Jakun-Delivery: 4182
X-Jakun-Signature: t=1761643964,v1=5f0c…
{"id": "evt_90211", "type": "record.stage_changed", "object": "lead",
"record_id": "3f1c2a9e-8d3b-4c55-9a51-2e0c0b7f4d11",
"actor": {"kind": "user", "id": "7d1e…"},
"changes": {"stage": {"before": "new", "after": "contacted"}},
"data": {…}, "occurred_at": "2026-10-28T09:32:44+00:00"}
id is stable across retries — use it to ignore repeats. X-Jakun-Delivery is
the delivery attempt chain you see in the log.
Verify the signature#
Same scheme as inbound events: HMAC-SHA256 of "<t>." + raw body, reject if
t is more than 300 seconds off.
import hashlib, hmac, os, time
from flask import Flask, abort, request
app = Flask(__name__)
SECRET = os.environ["JAKUN_WEBHOOK_SECRET"].encode()
@app.post("/jakun")
def jakun():
raw = request.get_data() # raw bytes, before any JSON parsing
parts = dict(p.split("=", 1) for p in request.headers.get("X-Jakun-Signature", "").split(","))
ts = int(parts.get("t", "0"))
want = hmac.new(SECRET, f"{ts}.".encode() + raw, hashlib.sha256).hexdigest()
if abs(time.time() - ts) > 300 or not hmac.compare_digest(want, parts.get("v1", "")):
abort(400)
event = request.get_json()
# … handle, idempotently by event["id"]
return "", 204
import crypto from "node:crypto";
import express from "express";
const app = express();
app.post("/jakun", express.raw({ type: "application/json" }), (req, res) => {
const parts = Object.fromEntries((req.get("X-Jakun-Signature") || "")
.split(",").map((p) => p.split("=", 2)));
const ts = Number(parts.t || 0);
const want = crypto.createHmac("sha256", process.env.JAKUN_WEBHOOK_SECRET)
.update(`${ts}.`).update(req.body).digest("hex");
const ok = parts.v1 && want.length === parts.v1.length &&
crypto.timingSafeEqual(Buffer.from(want), Buffer.from(parts.v1));
if (!ok || Math.abs(Date.now() / 1000 - ts) > 300) return res.sendStatus(400);
const event = JSON.parse(req.body);
// … handle, idempotently by event.id
res.sendStatus(204);
});
Retries#
Any 2xx within 10 seconds is success. Anything else — other codes, timeouts,
connection errors, redirects (not followed) — is retried:
| Attempt | 1 | 2 | 3 | 4 | 5 |
|---|---|---|---|---|---|
| Next try after | 1 min | 5 min | 30 min | 2 h | 6 h → dead |
After the fifth failure the delivery is dead. Every attempt is in the delivery log
with the status code, the first 2 KB of your answer and the time it took. Retry puts any
delivery — dead or delivered — back in the queue.
Manage#
- Pause a subscription to stop deliveries; resuming resets the failure counter.
- Rotate secret — new secret shown once; the old one stops working immediately.
- Deliver now runs the queue for your tenant without waiting for the worker.
All of this is also in the API reference (web session of an owner or admin).