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#

FieldType
idstring ≤ 128Unique per sender. Use the id from your system (call id, message id).
typestringSee event types. Unknown types are stored, not rejected.
sourcestringYour product: cbot, virtual_pbx, sms-geteway, bkg, jatid, jaryk, jakonto, jajob, soge, danadresse. Must be allowed for the key.
occurred_atISO 8601When it happened at your side (optional).
dataobjectType-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#

HTTPBodyMeaning
200status: processedKey in live; written to the CRM.
200status: dry_runKey in dry_run; processed and rolled back.
200status: duplicateAlready received; original_status and result of the first time.
200status: storedNo handler for this type yet; kept in the journal and can be processed later.
401bad_key, bad_signature, stale_signatureUnknown or revoked key, wrong signature, clock off by more than 300 s.
403source_not_allowed, no_roleThe key may not send for this source, or has no valid role.
400 / 413bad_request, too_largeEnvelope invalid or body over 256 KB.
422handler_failedThe handler raised; the event is failed in the journal. Fix and resend with the same id.
429rate_limitedOver 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#

typeSent bydataWhat JaKun does
contact_eventcbot, virtual_pbx, sms-getewaychannel, 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 / .canceledbkgbooking_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 / .updatedjatidentry_id, worker{ref,name}, started_at, ended_at, site_id or address_id, lead_id?Counts minutes on the case or site.
contact.verifiedcbot, sms-geteway, soge, danadressekind (phone, email, company, address), value, result, method, party_id?, evidenceMarks the phone or email as verified, sets CVR or a verified address. One-time codes are never stored.
reminder.sent / .repliedjarykchannel, text, contact, topicTimeline entry on the case.
anomaly.detectedjakontotitle, detailsTask 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.