Configurare i webhook e verificare la firma.

Gli eventi

Un webhook è un indirizzo del tuo server a cui inviamo un evento non appena si verifica. Gli eventi sono sei:

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 arriva al primo rimborso parziale e al rimborso completo. Un checkout mai pagato che scade non è un annullamento: in quel caso non arriva alcun evento.

Configurare un webhook

I programmi possono anche registrare autonomamente i webhook: POST /v1/webhooks con una chiave che abbia webhooks:manage, più il permesso di lettura dei dati che il webhook invia (forms:read per gli eventi dei moduli, orders:read per gli ordini).

1. 1Nella dashboard apri l'area Sviluppatore.
2. 2In “Webhook” inserisci l'indirizzo del tuo destinatario: inizia con https.
3. 3In “Quali eventi?” scegli cosa vuoi ricevere e fai clic su “Crea webhook”.
4. 4Copia nel tuo destinatario il segreto che compare subito dopo.
5. 5Fai clic su “Invia test”: il risultato compare subito sotto.

Cosa arriva

Ogni evento è un POST con JSON. In data.object l'oggetto ha la stessa forma che nell'API: un ordine come in GET /v1/orders/{id}, una risposta come nell'elenco delle risposte. Per gli eventi dei moduli, data.form indica inoltre a quale modulo appartiene la risposta.

{
  "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 }
      ]
    }
  }
}

Verificare la firma

Ogni chiamata contiene l'intestazione KENJTEC-Signature: t=<ora>,v1=<firma>. La firma è un HMAC-SHA256 calcolato sull'ora, un punto e il corpo invariato della richiesta, con il segreto del tuo webhook come chiave. Scarta tutto ciò la cui ora risale a più di cinque minuti fa.

Esegui la verifica sul corpo grezzo, prima di analizzare il JSON: basta uno spazio diverso per ottenere una firma diversa. Trovi il segreto in qualsiasi momento in “Mostra il segreto”; “Rinnova il segreto” invalida immediatamente quello vecchio.

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", ""))

Lo stesso evento può arrivare due volte, ad esempio quando il tuo server risponde ma la risposta non ci raggiunge. L'identificativo in id (presente anche nell'intestazione KENJTEC-Event-Id) resta lo stesso: memorizzalo ed elabora ogni evento una sola volta.

Quando qualcosa non arriva

Viene considerata consegnata qualsiasi risposta con uno stato da 200 a 299 entro dieci secondi. Non seguiamo i reindirizzamenti.

Se un evento non arriva, riproviamo: dopo 1, 5 e 30 minuti, dopo 2, 6 e 12 ore e due volte dopo 24 ore, per poco più di tre giorni. Se cinque eventi consecutivi non arrivano definitivamente, disattiviamo il webhook; la dashboard indica allora il motivo e “Riattiva” lo ripristina.

In “Registro” vedi ogni consegna degli ultimi 30 giorni con stato e contenuto. Da lì puoi inviare di nuovo qualsiasi evento con “Invia di nuovo”.

I webhook vengono inviati solo a indirizzi https pubblici. Non accettiamo indirizzi di reti interne né indirizzi di KENJTEC stessa.