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 trasporta sia un ordine status e 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
A 2xx (ad es. 200) oppure un 301 / 302 è considerato un successo. 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.
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.