Scopo

Un webhook è una chiamata POST che Qapla' fa verso un URL vostro quando succede qualcosa a una spedizione: cambia stato, il corriere registra un nuovo evento. Invece di interrogare l'API per sapere se qualcosa è cambiato, ricevete il fatto appena lo conosciamo.

I webhook v2 sono la generazione che accompagna l'API v2:

• stesso schema dell'API: il payload contiene la spedizione nella stessa forma di GET /v2/shipments, quindi chi integra ha un solo modello dati;
• firmati: ogni richiesta porta un HMAC-SHA256 del corpo, verificabile con un secret che conoscete solo voi e noi;
• configurabili: scegliete quando ricevere (solo i cambi di stato, la prima volta in uno stato, ogni evento del corriere) e per quali stati;
• affidabili: successo = qualunque 2xx, retry con backoff per circa 22 ore, consegne fallite conservate e rimandabili.

Configurazione

Un webhook si configura dal Control Panel, in Impostazioni canale → Aggiornamenti → «Webhook v2». Dalla stessa pagina si mandano i test, si ruota il secret, si consultano e si rimandano le consegne e si riattiva un endpoint spento. L'endpoint appartiene al canale: chi ha più canali lo configura su ognuno, anche con lo stesso URL. Ogni canale può avere fino a 5 endpoint (contano anche quelli spenti), per esempio l'ERP che riceve solo i cambi di stato e il customer care che riceve ogni evento.

Alla creazione il Control Panel mostra il secret di firma, nella forma whsec_ seguito da 64 caratteri esadecimali. Viene mostrato una volta sola: copiatelo subito nella configurazione del vostro ricevitore. Se lo perdete, si genera un secret nuovo (Rotazione del secret).

Tipi di evento

Altri tipi (etichette, resi) si aggiungeranno nello stesso catalogo. Il tipo arriva sia nel corpo (type) sia nell'header X-Qapla-Event-Type.

Trigger

Il trigger decide quando un evento della spedizione diventa una consegna verso il vostro endpoint. Lo stato Qapla' è una coppia stato + dettaglio (per esempio EXCEPTION con dettaglio «giacenza»): è su questa coppia che ragionano i primi due trigger.

Il trigger in uso arriva nel payload come data.trigger.

Filtro per stato

statuses è una lista di nomi di stato Qapla'. Vuota = tutti gli stati. Si applica dopo il trigger e solo sullo stato, mai sul dettaglio: ["EXCEPTION"] prende tutte le eccezioni, qualunque sia il dettaglio. Se vi servono solo alcuni dettagli, filtrateli dal vostro lato con data.event.statusDetailId.

Valori ammessi: WAITING_TO_COMPUTE, PENDING, INFO_RECEIVED, IN_TRANSIT, OUT_FOR_DELIVERY, FAILED_ATTEMPT, EXCEPTION, DELAY, PICKUP_POINT, DEPARTED, PROCESSING, RETURNED, DELIVERED. Un nome sconosciuto è un errore di configurazione.

Sezioni opzionali

include aggiunge al payload sezioni che di default non ci sono. Oggi accetta un solo valore:

Lo schema resta uno: il campo consignee c'è o non c'è, non cambia forma. include è una lista e non un sì/no perché potrà accogliere altre sezioni senza rompere il contratto.

Evento di test

Dal Control Panel si può mandare subito un evento webhook.test all'endpoint. È firmato col vostro secret vero, con gli stessi header di una consegna reale: serve a verificare la firma prima di andare live. Il Control Panel mostra il codice HTTP che avete risposto, la durata e l'eventuale errore.

• stesso envelope di shipment.updated, con una spedizione d'esempio fissa (non una vostra spedizione); consignee c'è solo se l'endpoint ha include: ["consignee"];
• l'id ha la forma evt_test_… ed è diverso a ogni test;
• un tentativo solo: non si ritenta e non finisce fra le consegne. Un test fallito non conta per gli avvisi e lo spegnimento; un test riuscito (2xx) invece riporta l'endpoint sano, azzerando il conteggio dei fallimenti.

Il ricevitore deve rispondere 2xx anche a webhook.test, e non deve trattarlo come un aggiornamento reale.

Struttura

Un evento per richiesta, niente batch. Content-Type: application/json, UTF-8.

Nuovi campi possono comparire nella risorsa (e quindi nel webhook) senza cambio di apiVersion: il ricevitore deve ignorare i campi che non conosce.

Ordine e duplicati

L'ordine di arrivo non è garantito. Le consegne sono indipendenti e possono viaggiare in parallelo: un evento vecchio in retry non blocca quelli nuovi. È una scelta: una consegna in serie farebbe aspettare ore una «consegnata» dietro un errore temporaneo di un evento precedente.

Lo stesso evento può arrivare più di una volta: un retry dopo un timeout in cui avevate già elaborato la richiesta, un replay. Usate id (o X-Qapla-Event-Id) come chiave di idempotenza: se l'avete già elaborato, rispondete 2xx e non fate altro. Una consegna fallita è rimandabile per 30 giorni (Replay): conservate gli id almeno per quel periodo.

Se più endpoint dello stesso canale sottoscrivono lo stesso evento, ognuno riceve la sua consegna con lo stesso id.

Firma

Ogni richiesta porta l'header:

X-Qapla-Signature: t=1791015120,v1=961fde4b87a60528ed28100be4badc6dcf1d64ce84b82f2a3fe9b077f45c0d2a

• t è il momento dell'invio, in secondi Unix;
• v1 è l'HMAC-SHA256 in esadecimale minuscolo della stringa "<t>.<corpo grezzo>", con chiave il secret dell'endpoint così com'è, prefisso whsec_ compreso;
• durante una rotazione del secret arrivano due v1, uno per ogni secret valido: la richiesta è autentica se almeno uno corrisponde.

Per verificare:

1. leggete il corpo grezzo, i byte come sono arrivati, prima di qualsiasi parsing JSON. Ricodificare il JSON cambia spazi e escape e la firma non torna più;
2. estraete t e tutti i v1 dall'header;
3. rifiutate la richiesta se t si discosta dal vostro orologio di più di 5 minuti (protezione dal replay di una richiesta intercettata);
4. calcolate l'HMAC-SHA256 di t + "." + corpo col vostro secret e confrontatelo con ogni v1 a tempo costante (hash_equals, crypto.timingSafeEqual, hmac.compare_digest), mai con ==;
5. firma non valida: rispondete 401 o 403 e scartate. Non verrà ritentata (Retry).

Lo schema è lo stesso delle Courier Events API, che usano la firma nella direzione opposta.

Verifica della firma

Implementazioni complete, senza dipendenze esterne. Tutte e tre accettano la richiesta se almeno un v1 corrisponde, quindi funzionano anche durante una rotazione.

<?php
/**
 * True when at least one v1 in X-Qapla-Signature matches and t is within the tolerance.
 * $rawBody: the request body exactly as received, before any json_decode.
 */
function qaplaSignatureIsValid(string $rawBody, string $header, string $secret, int $tolerance = 300, ?int $now = null): bool
{
    $timestamp = null;
    $signatures = [];
    foreach (explode(',', $header) as $part) {
        $pair = explode('=', trim($part), 2);
        if (count($pair) !== 2) {
            continue;
        }
        if ($pair[0] === 't') {
            $timestamp = $pair[1];
        } elseif ($pair[0] === 'v1') {
            $signatures[] = $pair[1];
        }
    }

    if ($timestamp === null || !ctype_digit($timestamp) || abs(($now ?? time()) - (int) $timestamp) > $tolerance) {
        return false;
    }

    $expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
    foreach ($signatures as $signature) {
        if (hash_equals($expected, $signature)) {
            return true;
        }
    }

    return false;
}

// Uso
$rawBody = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_QAPLA_SIGNATURE'] ?? '';
if (!qaplaSignatureIsValid($rawBody, $header, getenv('QAPLA_WEBHOOK_SECRET'))) {
    http_response_code(401);
    exit;
}
$event = json_decode($rawBody);

const crypto = require('crypto');

// rawBody: Buffer with the request body exactly as received (express.raw, not express.json).
function qaplaSignatureIsValid(rawBody, header, secret, toleranceSec = 300, now = Math.floor(Date.now() / 1000)) {
  let timestamp = null;
  const signatures = [];
  for (const part of String(header || '').split(',')) {
    const i = part.indexOf('=');
    if (i < 0) continue;
    const key = part.slice(0, i).trim();
    const value = part.slice(i + 1).trim();
    if (key === 't') timestamp = value;
    else if (key === 'v1') signatures.push(value);
  }

  if (!/^\d+$/.test(timestamp || '') || Math.abs(now - Number(timestamp)) > toleranceSec) return false;

  const expected = crypto.createHmac('sha256', secret).update(`${timestamp}.`).update(rawBody).digest();
  return signatures.some((signature) => {
    const received = Buffer.from(signature, 'hex');
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

// Uso con Express: il corpo deve restare un Buffer
app.post('/qapla/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  if (!qaplaSignatureIsValid(req.body, req.get('X-Qapla-Signature'), process.env.QAPLA_WEBHOOK_SECRET)) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body);
  res.sendStatus(204);
});

import hashlib
import hmac
import time


def qapla_signature_is_valid(raw_body: bytes, header: str, secret: str, tolerance: int = 300, now: float | None = None) -> bool:
    """raw_body: the request body exactly as received (e.g. Flask request.get_data())."""
    timestamp, signatures = None, []
    for part in (header or "").split(","):
        key, sep, value = part.strip().partition("=")
        if not sep:
            continue
        if key == "t":
            timestamp = value
        elif key == "v1":
            signatures.append(value)

    if timestamp is None or not timestamp.isdigit():
        return False
    if abs((time.time() if now is None else now) - int(timestamp)) > tolerance:
        return False

    expected = hmac.new(secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected, signature) for signature in signatures)

# Uso con Flask
@app.post("/qapla/webhook")
def qapla_webhook():
    if not qapla_signature_is_valid(request.get_data(), request.headers.get("X-Qapla-Signature", ""), os.environ["QAPLA_WEBHOOK_SECRET"]):
        abort(401)
    event = request.get_json()
    return "", 204

Vettore di prova

Per controllare la vostra implementazione senza aspettare un invio reale:

Con uno qualsiasi dei due secret la verifica deve riuscire, con un altro secret no. t è vecchio: per la prova disattivate il controllo della tolleranza o passate come «adesso» un istante entro 5 minuti da 1791015120 (gli esempi accettano un parametro now).

Rotazione del secret

Dal Control Panel si genera un secret nuovo, mostrato una volta sola. Il vecchio resta valido per 24 ore: in quella finestra ogni richiesta porta due v1, prima quello del secret nuovo, poi quello del vecchio. Dopo, solo il nuovo.

Per ruotare senza perdere consegne:

1. generate il secret nuovo dal Control Panel;
2. entro 24 ore mettetelo nella configurazione del ricevitore al posto del vecchio. Le richieste continuano a passare in entrambe le configurazioni, perché portano tutte e due le firme.

Ruotate subito se il secret è finito dove non doveva (log, repository, ticket).

IP di uscita

Il meccanismo di autenticazione è la firma, non l'indirizzo di provenienza: verificate sempre X-Qapla-Signature, anche se filtrate per IP.

Per chi deve comunque configurare un firewall, gli indirizzi da cui partono le nostre chiamate sono pubblicati qui, in testo semplice, uno per riga: https://cdn.qapla.it/sys/219a40582012cf87b88a782bdfe3a569. La lista può cambiare: se la usate, rileggetela periodicamente invece di copiarla una volta.

Richiesta

POST{il vostro url}

• solo https, con il certificato del server verificato: un certificato scaduto, autofirmato o per un altro host è un errore di connessione;
• timeout 10 secondi per l'intera richiesta, connessione compresa;
• nessun redirect: una risposta 3xx non viene seguita e vale come fallimento definitivo. Configurate l'URL finale;
• l'host viene risolto a ogni invio e deve risolvere solo a indirizzi pubblici. Se il DNS non risponde, si ritenta; se risolve a un indirizzo non pubblico, la consegna fallisce senza retry.

Risposta

Successo = qualunque 2xx. Il corpo della risposta viene ignorato: non serve rispondere {"result":"OK"} come nella v1, va benissimo un 204 vuoto.

Retry

Un esito ritentabile rimette in coda la consegna con un ritardo crescente, con un jitter di ±20% per non far ripartire tutto nello stesso istante. Al massimo 8 tentativi, distribuiti su circa 22 ore:

Retry-After (secondi o data HTTP) può solo allungare l'attesa, fino a un massimo di 12 ore: se indica meno del backoff previsto vale il backoff. Non aggiunge tentativi.

Avvisi e spegnimento

Un endpoint che fallisce per giorni non viene ritentato per sempre:

• se sono passate 24 ore dal primo fallimento senza nessuna consegna riuscita, mandiamo un primo avviso ad alertEmail;
• se ne sono passati 3 giorni, l'endpoint passa a disabled, con un secondo avviso;
• le soglie dipendono dal tempo trascorso dal primo fallimento, non dal numero di tentativi né da quanti eventi arrivano nel frattempo;
• il conteggio si azzera al primo 2xx, che sia una consegna o un evento di test mandato dal Control Panel: dopo aver sistemato il ricevitore, un test riuscito riporta l'endpoint sano.

Contano come fallimenti gli esiti non 2xx e gli errori di connessione. Un evento di test fallito non conta.

Quando l'endpoint si spegne (da solo o a mano):

• le consegne ancora in attesa di retry passano subito fra le fallite, e restano rimandabili col replay;
• da spento non si generano eventi: niente si accumula mentre è giù.

Si riattiva dal Control Panel (Impostazioni canale → Aggiornamenti → «Webhook v2»). Riparte pulito, senza un'ondata di eventi vecchi. Il buco si recupera con GET /v2/shipments?updatedAfter=…, partendo dall'ultimo aggiornamento che avete ricevuto.

Replay

Le consegne fallite (esauriti i retry, rifiutate con un 4xx, o interrotte dallo spegnimento dell'endpoint) si possono rimandare dal Control Panel, una per una o per intervallo di tempo, per 30 giorni dalla nascita della consegna. Il Control Panel mostra per ogni consegna stato, tentativi, ultimo codice HTTP ed errore.

Un replay rimette la consegna in coda come nuova: stesso id, X-Qapla-Delivery-Attempt che riparte da 1, di nuovo fino a 8 tentativi, e payload ricostruito con la spedizione com'è al momento del nuovo invio.

Lista delle consegne e replay sono in Impostazioni canale → Aggiornamenti → «Webhook v2».

Migrazione dalla v1

La v2 non sostituisce la v1 d'ufficio: si attiva per scelta, configurando un endpoint v2 sul canale, perché richiede modifiche al vostro codice. La v1 (documentazione) resta com'è, senza nuove funzioni: filtri e trigger esistono solo nella v2. Non c'è ancora una data di fine della v1; sarà annunciata con 12 mesi di preavviso.

Procedura consigliata

1. implementate il ricevitore v2: verifica della firma, deduplica su id, regola di scarto su statusDate, risposta 2xx veloce;
2. provatelo col vettore di prova;
3. mettetelo in produzione accanto al ricevitore v1, su un URL diverso;
4. dal Control Panel create l'endpoint v2 e salvate il secret: da qui la v1 del canale si ferma;
5. mandate un evento di test e controllate l'esito;
6. recuperate eventuali aggiornamenti persi nel passaggio con GET /v2/shipments?updatedAfter=….

Esempi

Punti aperti

Contatto: tech@qapla.it