Webhook

Invece di fare polling, registra un endpoint HTTPS e Nembol ti invia in POST un evento ogni volta che succede qualcosa: arriva un nuovo ordine da qualsiasi canale, cambiano le scorte, un'inserzione va online o finisce in errore.

Crea gli endpoint dalla dashboard (Impostazioni → Sviluppatori → Webhook) o tramite l'API. Ogni endpoint ha un signing secret, mostrato una sola volta alla creazione.

La consegna

POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: Nembol-Webhooks/1.0 (+https://developers.nembol.com/docs/webhooks)
X-Nembol-Event-Id: evt_2c91…
X-Nembol-Signature: t=1784900412,v1=5257a869e7…

{
  "id": "evt_2c91…",
  "type": "order.created",
  "api_version": "2026-07-24",
  "store_id": "5f2a…",
  "account_id": "acct_66f0a1",
  "created_at": "2026-07-24T16:03:12Z",
  "data": {
    "object": { "id": "ord_…", "channel": "etsy", "total": "49.90", "currency": "USD" }
  }
}

account_id è presente solo per i partner, su ogni evento di una delle loro aziende (sia nelle consegne sia in GET /events, operation.completed incluso): indica a quale azienda appartiene l'evento (lo stesso id di GET /accounts). Gli eventi del tuo negozio non lo hanno. Usalo per lo smistamento.

Ogni consegna contiene User-Agent: Nembol-Webhooks/1.0 e l'id dell'evento in X-Nembol-Event-Id. Fidati della firma, non di questi header: servono per i tuoi log e le regole del firewall. Una consegna viene inviata una volta per endpoint (si ripete solo nei retry dopo una risposta non 2xx, con lo stesso id evento).

data.object è la risorsa completa così com'è al momento della consegna (o della lettura da GET /events), non una copia congelata al momento della modifica. Cosa è cambiato si trova in data stesso: es. data.status e data.previous_status su listing.status_changed. Se nel frattempo la risorsa è cambiata di nuovo, data.object mostra già lo stato più recente e seguirà un evento più recente; ordina i tuoi aggiornamenti in base al created_at dell'evento.

Il contratto (leggilo due volte)

• Almeno una volta (at-least-once): lo stesso evento può essere consegnato più di una volta. Deduplica in base a event.id.
• Nessuna garanzia di ordine: gli eventi possono arrivare fuori ordine. Usa created_at (o rileggi la risorsa) invece di presumere una sequenza.
• Ogni evento viene consegnato, qualunque parte di Nembol lo abbia prodotto (chiamata API, dashboard, sincronizzazione ordini, webhook del canale). Se la consegna di un evento non è stata accodata al momento della sua creazione, Nembol la accoda entro pochi minuti (per eventi fino a 24 ore prima): arriva in ritardo, ma arriva sempre. Un endpoint riceve solo gli eventi creati dopo di esso. GET /events resta la via per la riconciliazione.
• Tipi sconosciuti: nuovi tipi di evento vengono aggiunti nel tempo. Ignora i tipi che non gestisci, e rispondi comunque 2xx.
• Rispondi in fretta con 2xx: entro 10 secondi, altrimenti la consegna è considerata fallita. Fai il lavoro vero in modo asincrono: metti in coda, poi rispondi 200.
• Verifica la firma prima di fidarti di qualsiasi cosa: verifica le firme.

Retry

Le consegne fallite (risposta non 2xx, timeout, errore di connessione) vengono ritentate con backoff esponenziale: 1m → 5m → 30m → 2h → 12h (circa 15 ore), poi la consegna viene segnata come fallita. Se un endpoint continua a fallire, viene disattivato automaticamente e il proprietario del negozio riceve una notifica nella dashboard e via email. Ogni tentativo è visibile nel registro delle consegne della dashboard, con la riconsegna manuale.

Ti sei perso un intero intervallo? Riconcilia con l'API del registro eventi: GET /events?created_after=… restituisce gli eventi degli ultimi 30 giorni.

Ultimo aggiornamento il 20 ottobre 2026