Ogni evento. Ogni payload. Firmato.
Fabrixa invia gli eventi relativi agli ordini al Suo endpoint in tempo reale. Il Suo server espone un endpoint POST pubblico; noi inviamo il corpo completo dell'ordine con una firma HMAC-SHA256 e il topic dell'evento nelle intestazioni. Verifichi la firma, restituisca rapidamente un codice di stato 200 ed elabori i dati in modo asincrono.
Tre intestazioni identificano e verificano la richiesta.
Ogni richiesta POST di webhook contiene le stesse tre intestazioni. Utilizzi x-webhook-topic per instradare l'evento e x-webhook-signature per verificarlo prima di fidarsi del body.
content-type è sempre application/json. x-webhook-signature è l'HMAC-SHA256 in formato Base64 del corpo del messaggio non elaborato. x-webhook-topic è il nome dell'evento.
{
"content-type": "application/json",
"x-webhook-topic": "order.updated",
"x-webhook-signature": "YmEwNjBhMGMy...MAxMw=="
}
Due topic, ad oggi.
Ogni webhook viene attivato da un valore x-webhook-topic specifico. Entrambi contengono l'oggetto ordine completo, quindi un unico gestore può eseguire uno switch sul topic.
È stato effettuato un nuovo ordine.
Si attiva quando viene creato un ordine in Fabrixa, sia tramite una richiesta API sia direttamente sulla piattaforma.
Un ordine esistente subisce una modifica.
Viene attivato quando cambiano i dettagli dell'ordine — ad esempio, quando lo stato dell'ordine o lo stato di evasione subiscono un'evoluzione.
Cosa indicano i campi di stato.
Il payload contiene l'ordine status oltre a un fulfillment_status. Le attivi per gestire lo stato del Suo ordine.
- Completed — spedito o ritirato e ricevuta confermata.
- Canceled — Il pagamento è stato annullato; la transazione non è andata a buon fine.
- On hold — l'ordine è temporaneamente bloccato.
- Imported — l'ordine è stato importato nella piattaforma.
- Unfulfilled — non ancora preparato o inviato.
- Partially fulfilled — alcuni articoli sono stati elaborati o spediti, altri sono in attesa di elaborazione.
- Scheduled — pianificati e programmati per l'elaborazione.
- Rejected — la richiesta di evasione è stata respinta.
- Fulfilled — completamente elaborati e consegnati o messi a disposizione.
Che aspetto ha il corpo.
Il payload order.updated completo, esattamente come documentato nel riferimento API: l'ordine, i relativi stati e le righe con i dettagli relativi alla variante, al prodotto e al file sorgente.
{
"id": 23069,
"number": "1250211835",
"comments": null,
"is_archived": false,
"status": "imported",
"fulfillment_status": "unfulfilled",
"purchased_at": "2025-04-17T16:17:21.000000Z",
"created_at": "2025-04-17T16:17:23.000000Z",
"updated_at": "2025-04-18T07:43:52.000000Z",
"rows": [
{
"id": 27954,
"quantity": 1,
"client_barcode": "1250211835",
"fulfillment_status": "unfulfilled",
"variant": {
"id": 293457,
"name": "Sherpa fleece deken",
"subtitle": "100x150",
"SKU": "SFD787231",
"product": {
"id": 5319, "name": "Sherpa fleece deken", "subtitle": "Sherpa fleece deken"
}
},
"sources": [
{
"type": "print",
"url": "https://storage.googleapis.com/fabrixa-api/…/120002795400.pdf",
"properties": { "fill_style": "contain" }
}
]
}
]
}
Ricalcoli l'HMAC, confronta i risultati e, se corrispondono, considera attendibile il corpo del messaggio.
Ricalcoli l'HMAC-SHA256 del payload grezzo della richiesta utilizzando la Sua chiave segreta, lo codifichi in base64 e lo confronti con x-webhook-signature. Utilizzare sempre un confronto a tempo costante (hash_equals) per evitare attacchi basati sul timing.
$payload = file_get_contents('php://input'); $secret = 'your-secret-key'; $expected = base64_encode( hash_hmac('sha256', $payload, $secret, true) ); $received = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? ''; // constant-time compare if (!hash_equals($expected, $received)) { http_response_code(403); exit('Invalid signature'); }
public function handle(Request $request)
{
$secret = 'your-secret-key';
$payload = $request->getContent();
$expected = base64_encode(
hash_hmac('sha256', $payload, $secret, true)
);
$received = $request->header('x-webhook-signature');
if (!hash_equals($expected, $received)) {
abort(403, 'Invalid signature');
}
// Continue processing…
}
I retry e la risposta che ci aspettiamo.
Fino a 10 tentativi, poi disattivato
Qualsiasi 2xx una risposta (ad es. 200) viene considerata un esito positivo, così come un 301 o 302 reindirizzamento. Qualsiasi 4xx, 5xx o timeout attiva un nuovo tentativo — fino a un massimo di 10 in totale. Dopo il decimo tentativo fallito, il webhook viene disattivato.
Restituisce rapidamente il codice di stato 200, elaborazione asincrona
Rispondere con 200 OK il più rapidamente possibile, quindi gestire il payload in modo asincrono tramite un’attività in background o una coda. Un endpoint lento può essere considerato un errore anche se alla fine va a buon fine.
Webhook: le risposte
Come posso verificare la firma di un webhook Fabrixa?
Ricalcoli l'HMAC-SHA256 del corpo della richiesta non elaborato utilizzando la Sua chiave segreta, codifica il risultato in base64 e confrontalo con l'intestazione x-webhook-signature utilizzando un confronto a tempo costante, come ad esempio hash_equals. Fabrixa fornisce esempi pratici in PHP grezzo e Laravel; qualsiasi discrepanza deve essere respinta prima che il payload venga elaborato.
Quali eventi webhook invia Fabrixa?
Fabrixa invia due eventi, identificati dall'intestazione x-webhook-topic: order.created, attivato quando viene effettuato un ordine tramite API o direttamente sulla piattaforma, e order.updated, attivato quando cambia lo stato dell'ordine o lo stato di evasione. Entrambi contengono l’oggetto ordine completo, pertanto è possibile utilizzare un unico gestore per l’argomento.
Quante volte Fabrixa riprova a eseguire un webhook che non è andato a buon fine?
Fabrixa riprova a inviare un webhook fino a 10 volte quando la risposta non è un codice 2xx, 301 o 302. Qualsiasi codice di errore 4xx, 5xx o timeout viene considerato un errore e attiva un nuovo tentativo; dopo il decimo tentativo fallito, il webhook viene disattivato, pertanto l’endpoint dovrebbe restituire rapidamente un codice 200 ed elaborare il payload in modo asincrono.
Quali intestazioni sono incluse in una richiesta webhook Fabrixa?
Ogni richiesta POST del webhook contiene tre intestazioni: content-type, sempre application/json; x-webhook-topic, che indica il nome dell’evento, ad esempio order.updated; e x-webhook-signature, la firma HMAC-SHA256 codificata in base64 del corpo grezzo. Utilizza l’argomento per instradare l’evento e la firma per verificarlo prima di considerare attendibile il payload.
Quali stati dell'ordine compaiono nel payload di un webhook Fabrixa?
Il payload contiene un campo "status" con quattro valori — "Completed", "Canceled", "On hold" e "Imported" — e un campo separato "fulfillment_status" con cinque valori: "Unfulfilled", "Partially fulfilled", "Scheduled", "Rejected" e "Fulfilled". Un singolo evento "order.updated" può segnalare una modifica in uno dei due campi.
Configuri l'endpoint del Suo webhook.
La guida all'integrazione illustra passo dopo passo come registrare il proprio endpoint e gestire l'intero ciclo di vita dell'ordine. Il riferimento API completo contiene lo schema completo del payload.