Webhook

Vellaro può notificare il tuo backend quando succede qualcosa nel negozio (ordine creato, pagato, spedito, prodotto modificato), così puoi sincronizzare ERP, gestionali o pipeline esterne senza polling.

Come funziona

Registri uno o più endpoint dal pannello admin o con la Admin API (POST /admin/webhooks, permesso system), scegliendo gli eventi.
Vellaro effettua una POST al tuo URL a ogni evento sottoscritto, con un payload JSON che descrive l’evento e la risorsa.
La richiesta è firmata: verifica la firma con il tuo secret prima di fidarti del contenuto.
Rispondi 2xx entro 10 secondi per confermare la ricezione; gli invii falliti vengono ritentati.

curl -X POST "$BASE/api/v1/admin/webhooks" -H "Authorization: Bearer $STAFF" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://erp.example.com/hooks/vellaro","events":["order.paid","order.shipped"]}'

La risposta contiene il secret di firma (whsec_...), mostrato una sola volta: salvalo subito. Le letture successive mostrano solo secret_last_four.

Regole dell’URL

L’URL deve essere https verso un host pubblico, senza credenziali nell’URL. Il controllo vale al salvataggio (con una verifica DNS) e di nuovo a ogni consegna:

`error_code` (422)	Quando
`webhooks.url_https_required`	l’URL non inizia con `https://`
`webhooks.url_not_public`	l’host è un indirizzo o un nome di rete interna (IP privati, `localhost`, nomi senza dominio, host che risolvono verso reti interne)
`webhooks.url_invalid`	URL vuoto, malformato, con credenziali o porta non valida

Una consegna verso una destinazione che nel frattempo risolve su una rete interna risulta failed, senza nuovi tentativi. I redirect non vengono seguiti: un 3xx conta come errore.

Eventi

GET /admin/webhooks/events restituisce l’elenco degli eventi sottoscrivibili:

Evento	Quando
`order.created`	nuovo ordine dal checkout
`order.paid`	pagamento incassato (gateway, buono regalo o pagamento registrato a mano)
`order.shipped`	l’ordine passa a «spedito»
`order.refunded`	rimborso totale o parziale, anche con lo stato «Rimborsato»: il denaro torna al cliente. `payment_status` e `amount_refunded` dicono quanto
`product.created`	prodotto creato, anche da import CSV
`product.updated`	prodotto modificato, anche da import CSV
`product.deleted`	prodotto eliminato

Gli invii di prova portano l’evento webhook.test, che non si può sottoscrivere.

Payload

{
  "event": "order.paid",
  "occurred_at": "2026-10-10T09:31:12.402117+00:00",
  "tenant_id": "7f3e9a1b-4c2d-4e5f-8a9b-0c1d2e3f4a5b",
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "status": "processing",
    "payment_status": "paid",
    "payment_method": "stripe",
    "subtotal": "1199.00",
    "shipping_cost": "0.00",
    "total": "1079.10",
    "amount_refunded": "0.00",
    "currency": "EUR",
    "customer_email": "mario.rossi@example.com",
    "tracking_number": null,
    "created_at": "2026-10-10T09:30:00+00:00"
  }
}

Per gli eventi product.*, data contiene id, name, slug e is_active. Per avere il dettaglio completo, rileggi la risorsa con la Admin API.

Verifica della firma

Ogni richiesta porta questi header:

Header	Contenuto
`X-Vellaro-Event`	il nome dell’evento
`X-Vellaro-Delivery`	l’id della consegna (uguale in tutti i tentativi della stessa consegna)
`X-Vellaro-Timestamp`	secondi Unix del tentativo
`X-Vellaro-Signature`	`sha256=` seguito dall’HMAC-SHA256 esadecimale di `<timestamp>.` più il corpo grezzo, con il tuo secret

Calcola la firma sui byte ricevuti, non su un JSON ri-serializzato, confrontala in tempo costante e scarta i timestamp troppo vecchi.

import crypto from "node:crypto";

// rawBody: Buffer con il corpo esatto della richiesta
export function verifyVellaro(rawBody, headers, secret) {
  const ts = headers["x-vellaro-timestamp"] ?? "";
  const sig = headers["x-vellaro-signature"] ?? "";
  if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(`${ts}.`).update(rawBody).digest("hex");
  const a = Buffer.from(sig);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

import hashlib
import hmac
import time

def verify_vellaro(raw_body: bytes, headers, secret: str) -> bool:
    ts = headers.get("X-Vellaro-Timestamp", "")
    sig = headers.get("X-Vellaro-Signature", "")
    if not ts.isdigit() or abs(time.time() - int(ts)) > 300:
        return False
    mac = hmac.new(secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256)
    return hmac.compare_digest(sig, "sha256=" + mac.hexdigest())

Tentativi e idempotenza

Ogni risposta diversa da 2xx (redirect compresi), un timeout o un errore di rete è un tentativo fallito. La consegna viene ritentata con attesa crescente (1, 2, 4, 8 e 16 minuti).
I tentativi della stessa consegna hanno lo stesso X-Vellaro-Delivery. Un rinvio manuale crea invece una consegna nuova con lo stesso payload: rendi idempotente l’elaborazione (per esempio su event, data.id e occurred_at).
Rispondi subito 2xx e fai il lavoro pesante in coda.

Strumenti di gestione

Tutte le rotte sono sotto /admin/webhooks/{id} (permesso system); un webhook di un altro negozio risponde 404.

Rotta	Cosa fa
`POST /admin/webhooks/{id}/test`	invia subito un evento `webhook.test` firmato, un solo tentativo, anche a webhook in pausa. Risponde `ok`, `duration_ms` e la consegna registrata
`GET /admin/webhooks/{id}/deliveries`	registro delle consegne, dalla più recente, paginato e filtrabile con `status=pending`, `success` o `failed`
`POST /admin/webhooks/{id}/deliveries/{delivery_id}/redeliver`	rinvia quell’evento come consegna nuova: 202 con la consegna `pending`. Su un webhook in pausa 409 `webhooks.inactive`; consegna inesistente 404 `webhooks.delivery_not_found`
`POST /admin/webhooks/{id}/rotate-secret`	genera un secret nuovo, mostrato una sola volta
`PATCH /admin/webhooks/{id}`	cambia `url`, `events` o `is_active` (un campo `null` resta invariato)

Ogni consegna del registro ha event_type, status, attempt, response_status, next_retry_at, delivered_at e response_body: un estratto sicuro della risposta del tuo endpoint (al massimo 256 caratteri stampabili), utile per riconoscere l’errore.

Dopo rotate-secret le firme usano subito il secret nuovo e quello vecchio smette di verificare. Prepara il tuo endpoint ad accettare entrambi i secret, ruota, poi togli il vecchio.

Per la consegna dei prodotti digitali non servono webhook: dopo il pagamento l’API emette link di download firmati, documentati nella API Reference.

Inizia

Guide

AI & MCP

Come funziona

Regole dell’URL

Eventi

Payload

Verifica della firma

Tentativi e idempotenza

Strumenti di gestione