IMMEDIATO
Consegna iniziale + tentativo 1
Prima consegna sull'evento. Se 5xx o timeout, riprovare 30 secondi dopo.
SVILUPPATORI - RIFERIMENTO AI WEBHOOK
Ordinare gli eventi del ciclo di vita, firmati e a prova di ritorsione.
I webhook si attivano ad ogni transizione di stato dell'ordine: ricevuto, stampato, spedito, fallito. JSON su HTTPS, firma HMAC-SHA256 per la verifica, coda di tentativi con backoff esponenziale fino a 24 ore. esponenziale fino a 24 ore. Riferimento agli eventi, esempi di codice di verifica della firma e politica di retry / dead-letter di seguito.
HMAC-SHA256 FIRMATO - ALMENO UNA VOLTA - 24 ORE DI RIPRESA - QUOTA DI SCARTO
TIPI DI EVENTO
Cinque eventi del ciclo di vita dell'ordine.
Abbonarsi a qualsiasi sottoinsieme sul sito PUT /v1/account/webhook
endpoint. La maggior parte delle integrazioni si abbona a tutti e cinque.
| Evento | Si accende quando | Azione tipica |
|---|---|---|
| ordine.ricevuto | L'Fabrixa ha accettato l'ordine e ha assegnato una ordine_id. Ack entro pochi secondi dal POST. | Aggiornare lo stato dell'ordine interno a "in produzione"; inviare la superficie al cliente finale. |
| ordine.stampato | Fase di stampa reattiva completata. Il capo passa al taglio e cucito. Tappa intermedia della produzione. | Facoltativo - alcuni team lo usano per le e-mail di "ordine in corso di realizzazione" dei clienti finali. |
| ordine.spedito | Controllo qualità, imballaggio e consegna al corriere. Emissione del numero di tracciamento. | Aggiornare lo stato dell'ordine a "spedito"; attivare la notifica di spedizione al cliente finale con l'URL di tracciamento. |
| ordine.consegnato | Il vettore ha confermato la consegna all'indirizzo del destinatario. | Attivare flussi post-acquisto: richiesta di recensione, upsell di prodotti correlati, ecc. |
| ordine.fallito | L'ordine non può essere completato: l'opera d'arte non è raggiungibile, l'indirizzo del destinatario non è valido, il tessuto non è disponibile per un periodo prolungato. | Aprire un ticket / avvisare le operazioni. Il carico utile include errore.codice per la logica di accensione. |
FORMA DEL CARICO
Stessa busta, dati specifici dell'evento.
Busta comune (evento, order_id, order_ref, timestamp) più una busta specifica dell'evento
dati oggetto. Consumare prima la busta; accendere evento per la forma dei dati.
ordine.spedito
# order.dispatched payload - POST all'URL del webhook POST /il tuo endpoint-webhook Tipo di contenuto: application/json X-Fabrixa-Evento: ordine.spedito X-Fabrixa-Firma: t=1715173928,v1=ab3c4... X-Fabrixa-Id di consegna: del_94kQ7r2L { "evento": "ordine.spedito", "order_id": "ord_8e6f4b2a", "ordine_ref": "shopify-1042", "timestamp": "2026-05-15T11:32:08Z", "production_hub": "PT", "dati": { "tracciamento": { "vettore": "DHL", "numero_di_tracciamento": "JJD0123456789", "tracking_url": "https://dhl.com/track/JJD0123456789", "consegna_prevista": "2026-05-19" }, "destinatario": { "nome": "Lena Costa", "città": "Porto", "paese": "PT" } } }
VERIFICA DELLA FIRMA
HMAC-SHA256 su (timestamp + corpo grezzo).
Verificare la firma prima dell'elaborazione. Usare il tasto corpo della richiesta grezzo - non un oggetto JSON riserializzato, altrimenti l'HMAC non corrisponderà. Il segreto di firma viene emesso una volta quando si imposta l'URL del webhook; la rotazione avviene tramite la dashboard.
verify-signature.js
// Esempio di Node.js / Express costitutivo crittografia = richiedere("crittografia"); app.posta("/webhook", espresso.grezzo({tipo: "application/json" }), (req, res) => { costitutivo signature = req.headers["x-fabrixa-firma"]; costitutivo [tPart, v1Part] = firma.spaccatura(","); costitutivo timestamp = tPart.spaccatura("=")[1]; costitutivo ricevuto = v1Part.spaccatura("=")[1]; // Rifiuta gli eventi più vecchi di 5 minuti (protezione replay) se (Matematica.addominali(Data.ora() / 1000 - timestamp) > 300) ritorno res.stato(400).fine(); costitutivo payload = `${timestamp}.${req.body.toStringa()}`; costitutivo previsto = crittografia .creareHmac("sha256", process.env.FABRIXA_WEBHOOK_SECRET). .aggiornamento(carico utile) .digest("esadecimale"); se (!crypto.timingSafeEqual(Tampone.da(ricevuto), Buffer.da(previsto))) { ritorno res.stato(401).fine(); } // Firma valida: elabora l'evento costitutivo evento = JSON.analizzare(req.body); handleEvent(evento); res.stato(200).fine(); });
Esempi equivalenti per Python (Flask), PHP, Ruby e Go si trovano nella cartella scripts della raccolta Postman. timingSafeEqual non usare l'uguaglianza delle stringhe, è vulnerabile agli attacchi di temporizzazione.
POLITICA DI RECESSO
Backoff esponenziale fino a 24 ore.
La consegna dei webhook è una volta sola. Se il vostro endpoint restituisce 5xx o va in timeout (timeout di 10 secondi), effettuiamo un nuovo tentativo con un programma di backoff esponenziale per un massimo di 24 ore. Dopo 24 ore di insuccesso, l'evento finisce in una coda di attesa che può essere riprodotta manualmente.
BACKOFF
Ripetizioni 2-8, esponenziale
60s → 5min → 30min → 2h → 6h → 12h → 24h. Ad ogni nuovo tentativo l'attesa è più lunga.
LETTERA MORTA
Dopo 24 ore dal guasto
Evento spostato nella coda delle lettere morte. Riproduzione manuale tramite dashboard o POST /v1/webhooks/replay/:delivery_id.
EVENTO ORDER.FAILED
Motivi di errore strutturati per la logica di accensione.
L'evento più importante dal punto di vista operativo. Il carico utile comprende una stabile errore.codice stringa - sicuro da attivare per l'instradamento automatico, la creazione di ticket o la messaggistica per i clienti finali.
ordine.fallito
{
"evento": "ordine.fallito",
"order_id": "ord_8e6f4b2a",
"ordine_ref": "shopify-1042",
"timestamp": "2026-05-13T09:14:22Z",
"dati": {
"errore": {
"codice": "artwork_unreachable",
"messaggio": "GET su artwork_url fallito (timeout 30s) dopo 3 tentativi".",
"ritentabile": vero,
"contesto": {
"url_opera_d_arte": "https://cdn.yourbrand.com/art/drop-001.png"
}
}
}
}
# Valori comuni dei codici di errore:
# artwork_unreachable - l'URL dell'opera d'arte non ha risposto
# artwork_invalid_format - impossibile analizzare il file (provare PNG / PDF vettoriale)
# artwork_resolution_low - DPI troppo basso per il prodotto scelto
# address_invalid - l'indirizzo del destinatario non è stato convalidato
# fabric_unavailable - tessuto base non disponibile da >7 giorni
# payment_method_failed - fatturazione su file rifiutata
# compliance_flag - ordine segnalato dall'esame di conformità
TEST
Attivare eventi campione senza ordini reali.
POST /v1/webhooks/test
invia un evento sintetico di qualsiasi tipo all'URL del webhook registrato.
Utile per testare il gestore prima di inviare ordini reali o per verificare un nuovo endpoint dopo la distribuzione.
un nuovo endpoint dopo una distribuzione.
I webhook della sandbox vengono inviati all'URL della sandbox. Utilizzare uno strumento di tunnelling (ngrok, Cloudflare Tunnel) per puntare i webhook della sandbox a localhost durante lo sviluppo. sviluppo.
POST /v1/webhooks/test
ricciolo -X POST $BASE_URL/v1/webhooks/test \ -H "Autorizzazione: Bearer $KEY" \ -H "Tipo di contenuto: application/json" \ -d '{ "evento": "ordine.spedito", "ordine_campione_id": "campione" }' # 200 OK { "delivery_id": "del_test_94kQ", "post_to": "https://your-tunnel.ngrok.io/webhook", "stato": "in coda" }
REGISTRARE IL WEBHOOK
Impostate l'URL una volta sola. Noi ci occupiamo della consegna.
Un URL webhook per account, a cui vengono inviati tutti i tipi di eventi. Filtro su
evento
nel proprio gestore. Configurazione tramite la guida all'integrazione.