Inbound events
Push calls, chats, SMS, bookings, hours and checks into JaKun: envelope, HMAC signature, idempotency, statuses and event types.
Other systems send what happened — a call, a chat, a booking, logged hours — to one address
per tenant. JaKun finds or creates the customer, opens a case and puts it in the right queue.
Retries are safe, every event is in the journal, and a new key starts in dry_run.
Send an event#
POST https://jakun.dk/api/v1/inbound/{tenant} with the raw JSON body and two headers:
X-JaKun-Key: key_…— the key id;X-JaKun-Signature: t=<unix>,v1=<hex>— HMAC-SHA256 with the signing secret over"<unix>." + raw body. The time must be within ±300 seconds of ours.
import hashlib, hmac, json, os, time, uuid
import httpx
def send(event_type: str, data: dict, *, event_id: str) -> dict:
body = json.dumps({"id": event_id, "type": event_type, "source": "cbot",
"occurred_at": "2026-10-28T09:12:44Z", "data": data}).encode()
ts = int(time.time())
mac = hmac.new(os.environ["JAKUN_SIGNING_SECRET"].encode(),
f"{ts}.".encode() + body, hashlib.sha256).hexdigest()
r = httpx.post(f"{os.environ['JAKUN_URL']}/api/v1/inbound/{os.environ['JAKUN_TENANT']}",
content=body, timeout=10, headers={
"Content-Type": "application/json",
"X-JaKun-Key": os.environ["JAKUN_KEY_ID"],
"X-JaKun-Signature": f"t={ts},v1={mac}"})
if r.status_code >= 500 or r.status_code == 429:
raise RuntimeError("retry later with the same id")
return r.json()
print(send("contact_event", {"channel": "web_chat", "external_id": "chat-77",
"text": "Nyt badeværelse 8 m²", "intent": "lead",
"contact": {"first_name": "Testa", "phone": "+4500000201"}},
event_id="chat-77"))
import crypto from "node:crypto";
export async function send(type, data, id) {
const body = JSON.stringify({ id, type, source: "cbot",
occurred_at: new Date().toISOString(), data });
const ts = Math.floor(Date.now() / 1000);
const mac = crypto.createHmac("sha256", process.env.JAKUN_SIGNING_SECRET)
.update(`${ts}.${body}`).digest("hex");
const r = await fetch(
`${process.env.JAKUN_URL}/api/v1/inbound/${process.env.JAKUN_TENANT}`, {
method: "POST", body,
headers: { "Content-Type": "application/json",
"X-JaKun-Key": process.env.JAKUN_KEY_ID,
"X-JaKun-Signature": `t=${ts},v1=${mac}` } });
if (r.status >= 500 || r.status === 429) throw new Error("retry later with the same id");
return r.json();
}
BODY='{"id":"chat-77","type":"contact_event","source":"cbot","data":{"channel":"web_chat","external_id":"chat-77","contact":{"phone":"+4500000201"}}}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$JAKUN_SIGNING_SECRET" -hex | sed 's/^.* //')
curl -X POST "$JAKUN_URL/api/v1/inbound/$JAKUN_TENANT" \
-H "Content-Type: application/json" \
-H "X-JaKun-Key: $JAKUN_KEY_ID" \
-H "X-JaKun-Signature: t=$TS,v1=$SIG" \
--data-raw "$BODY"
Sign the exact bytes you send. Re-serialising JSON after signing
(different spacing or key order) gives 401 bad_signature.
Envelope#
| Field | Type | |
|---|---|---|
id | string ≤ 128 | Unique per sender. Use the id from your system (call id, message id). |
type | string | See event types. Unknown types are stored, not rejected. |
source | string | Your product: cbot, virtual_pbx, sms-geteway, bkg, jatid, jaryk, jakonto, jajob, soge, danadresse. Must be allowed for the key. |
occurred_at | ISO 8601 | When it happened at your side (optional). |
data | object | Type-specific payload. Body ≤ 256 KB. |
Idempotency and retries#
Events are unique by (source, id). Sending the same event again returns
duplicate with the original status and result — so retry freely after a timeout.
A failed event may be sent again with the same id and is processed again.
Retry on network errors, 429 (after Retry-After) and 5xx,
with growing pauses (for example 10 s, 1 min, 5 min, 30 min). Don't retry 4xx other than 429:
the request itself is wrong.
Responses#
| HTTP | Body | Meaning |
|---|---|---|
| 200 | status: processed | Key in live; written to the CRM. |
| 200 | status: dry_run | Key in dry_run; processed and rolled back. |
| 200 | status: duplicate | Already received; original_status and result of the first time. |
| 200 | status: stored | No handler for this type yet; kept in the journal and can be processed later. |
| 401 | bad_key, bad_signature, stale_signature | Unknown or revoked key, wrong signature, clock off by more than 300 s. |
| 403 | source_not_allowed, no_role | The key may not send for this source, or has no valid role. |
| 400 / 413 | bad_request, too_large | Envelope invalid or body over 256 KB. |
| 422 | handler_failed | The handler raised; the event is failed in the journal. Fix and resend with the same id. |
| 429 | rate_limited | Over the limit of the key. |
{"data": {"event_id": "chat-77", "type": "contact_event", "mode": "dry_run",
"status": "dry_run", "result": {"outcome": "lead", "lead_id": "3f1c…",
"party_id": "9a0e…", "contact_event_id": "c41d…"}}}
Event types#
| type | Sent by | data | What JaKun does |
|---|---|---|---|
contact_event | cbot, virtual_pbx, sms-geteway | channel, external_id, text, contact{first_name,last_name,phone,email}, intent (lead, callback_request, open_question, logged, ignored) | Finds the customer by 8-digit phone or email, opens a case, puts it in a queue; first reply sets first response. |
booking.created / .updated / .canceled | bkg | booking_id, starts_at, duration_min, title, contact, address_id (DAR), lead_id? | Mirrors the booking in the calendar, links the site, moves the case to meeting booked. |
time_entry.recorded / .updated | jatid | entry_id, worker{ref,name}, started_at, ended_at, site_id or address_id, lead_id? | Counts minutes on the case or site. |
contact.verified | cbot, sms-geteway, soge, danadresse | kind (phone, email, company, address), value, result, method, party_id?, evidence | Marks the phone or email as verified, sets CVR or a verified address. One-time codes are never stored. |
reminder.sent / .replied | jaryk | channel, text, contact, topic | Timeline entry on the case. |
anomaly.detected | jakonto | title, details | Task for the owner. |
job.*, candidate.* | jajob | — | Stored for now. |
Test data: Danish numbers +45 0000 0xxx belong to nobody — use them in examples and tests.
Journal#
Every event — including duplicates' first copy, failures and unknown types — is in
Indstillinger → Hændelseslog, filterable by source, type and status, with the payload, the
result and the error. Owners can process again a failed, stored or
dry_run event with the key's current mode. Test events from Forbindelser have
ids starting with jakun-test- and always stay in dry_run.