Ställa in webhooks och verifiera signaturen.

Händelserna

En webhook är en adress på din server som vi skickar en händelse till så snart den inträffar. Det finns sex händelser:

form.response.created   Eine neue Antwort auf eines deiner Formulare
form.response.updated   Jemand hat seine Antwort über den Bearbeitungslink geändert
order.paid              Eine Bestellung ist bezahlt
order.fulfilled         Eine Bestellung ist versendet oder übergeben
order.canceled          Eine bestätigte Bestellung wurde storniert
order.refunded          Eine Bestellung wurde erstattet

order.refunded skickas vid den första delåterbetalningen och vid den fullständiga återbetalningen. En kassa som aldrig betalades och som löper ut är ingen annullering – för den skickas ingen händelse.

Ställa in en webhook

Program kan också registrera webhooks själva: POST /v1/webhooks med en nyckel som har webhooks:manage – och dessutom läsbehörigheten för de data som webhooken skickar (forms:read för formulärhändelser, orders:read för beställningar).

1. 1Öppna området Utvecklare i dashboarden.
2. 2Ange din mottagares adress under ”Webhooks” – den börjar med https.
3. 3Välj under ”Vilka händelser?” vad du vill ta emot och klicka på ”Skapa webhook”.
4. 4Kopiera hemligheten som sedan visas till din mottagare.
5. 5Klicka på ”Skicka test” – resultatet visas direkt nedanför.

Vad som kommer fram

Varje händelse är en POST med JSON. I data.object finns objektet i samma form som i API:et – en beställning som i GET /v1/orders/{id}, ett svar som i listan över svar. Vid formulärhändelser anger data.form dessutom vilket formulär svaret hör till.

{
  "id": "evt_Q2x9kLmP4vT7aB1cD3eF5gH7",
  "object": "event",
  "type": "order.paid",
  "api_version": "2026-09-23",
  "created_at": "2026-09-23T14:05:12Z",
  "data": {
    "object": {
      "id": 5531,
      "object": "order",
      "number": 42,
      "status": "confirmed",
      "payment_status": "paid",
      "currency": "EUR",
      "total": 3890,
      "customer": { "email": "mara@example.com", "name": "Mara Sol" },
      "items": [
        { "name": "Kaffeebohnen, 500 g", "sku": "KAF-500", "quantity": 2, "unit_price": 1690 }
      ]
    }
  }
}

Verifiering av signaturen

Varje anrop har rubriken KENJTEC-Signature: t=<tid>,v1=<signatur>. Signaturen är en HMAC-SHA256 över tiden, en punkt och förfrågans oförändrade brödtext – med din webhooks hemlighet som nyckel. Kassera allt vars tid ligger mer än fem minuter tillbaka.

Verifiera mot den råa brödtexten innan du tolkar JSON-datat: redan ett annorlunda mellanslag ger en annan signatur. Hemligheten hittar du när som helst under ”Visa hemlighet”; ”Förnya hemlighet” gör den gamla ogiltig omedelbart.

import crypto from "node:crypto";

// raw: the unparsed request body (Buffer), header: the KENJTEC-Signature header
export function verify(raw, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret)
    .update(`${parts.t}.`).update(raw).digest("hex");
  const given = String(parts.v1 ?? "");
  return given.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(given));
}

import hashlib, hmac, time

def verify(raw: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Samma händelse kan komma fram två gånger – till exempel om din server svarar men svaret inte når oss. Identifieraren i id (även i rubriken KENJTEC-Event-Id) förblir då densamma: spara den och behandla varje händelse bara en gång.

När något inte kommer fram

Varje svar med en status från 200 till 299 inom tio sekunder räknas som levererat. Vi följer inte omdirigeringar.

Om en händelse inte kommer fram försöker vi igen: efter 1, 5 och 30 minuter, efter 2, 6 och 12 timmar och två gånger efter 24 timmar – i drygt tre dagar. Om fem händelser i rad slutgiltigt inte kommer fram stänger vi av webhooken; i dashboarden står det då varför, och ”Slå på igen” återställer den.

Under ”Logg” ser du varje leverans från de senaste 30 dagarna med status och innehåll. Därifrån kan du skicka varje händelse en gång till med ”Skicka igen”.

Webhooks skickas bara till offentliga https-adresser. Adresser i interna nätverk och adresser som tillhör KENJTEC själv accepterar vi inte.