Fiecare eveniment. Fiecare încărcătură. Semnat.
Fabrixa transmite evenimentele legate de comenzi către punctul dumneavoastră de acces în timp real. Serverul dumneavoastră pune la dispoziție un singur punct de acces public de tip POST; noi trimitem corpul complet al comenzii, împreună cu o semnătură HMAC-SHA256 și subiectul evenimentului în antete. Verifică semnătura, returnează rapid codul de stare 200 și procesează asincron.
Trei antete identifică și verifică solicitarea.
Fiecare cerere POST de tip webhook conține aceleași trei antete. Utilizați x-webhook-topic pentru a redirecționa evenimentul și x-webhook-signature pentru a verifica acest lucru înainte de a avea încredere în organism.
content-type este întotdeauna application/json. x-webhook-signature este codul Base64 HMAC-SHA256 al corpului mesajului în format brut. x-webhook-topic este numele evenimentului.
{
"content-type": "application/json",
"x-webhook-topic": "order.updated",
"x-webhook-signature": "YmEwNjBhMGMy...MAxMw=="
}
Astăzi vom aborda două subiecte.
Fiecare webhook este declanșat de un anumit x-webhook-topic valoare. Ambele conțin obiectul complet al comenzii, astfel încât un singur handler poate prelua comanda pe tema respectivă.
Se plasează o nouă comandă.
Se declanșează atunci când se creează o comandă în Fabrixa — fie printr-o solicitare API, fie direct în platformă.
O comandă existentă se modifică.
Se declanșează atunci când se modifică detaliile comenzii — de exemplu, când starea comenzii sau starea procesării acesteia evoluează.
Ce pot indica câmpurile de stare.
Sarcina utilă transmite comanda status precum și un altul fulfillment_status. Activează aceste opțiuni pentru a-ți gestiona propria stare a comenzii.
- Completed — livrat sau ridicat, cu confirmarea primirii.
- Canceled — plata a fost anulată; tranzacția nu s-a finalizat.
- On hold — comanda este blocată temporar.
- Imported — comanda a fost importată în platformă.
- Unfulfilled — încă nu a fost pregătit sau trimis.
- Partially fulfilled — unele articole au fost procesate sau expediate, altele sunt în așteptare.
- Scheduled — planificate și programate pentru procesare.
- Rejected — cererea de îndeplinire a fost respinsă.
- Fulfilled — prelucrate integral și livrate sau puse la dispoziție.
Cum arată corpul.
Versiunea completă order.updated conținutul, exact așa cum este documentat în documentele de referință API — comanda, stările acesteia și rândurile cu detalii privind varianta, produsul și sursa.
{
"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" }
}
]
}
]
}
Recalculează HMAC-ul, compară rezultatele, apoi acceptă conținutul.
Recalculează valoarea HMAC-SHA256 a conținutului brut al cererii folosind cheia ta secretă, codific-o în format Base64 și compar-o cu x-webhook-signature. Folosiți întotdeauna o comparație cu timp constant (hash_equals) pentru a evita atacurile de tip 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…
}
Încercări repetate și răspunsul pe care îl așteptăm.
Până la 10 încercări, apoi funcția este dezactivată
Oricare 2xx răspunsul (de exemplu, 200) este considerat un succes, la fel ca și un 301 sau 302 redirecționare. Orice 4xx, 5xx sau expirarea timpului de așteptare declanșează o nouă încercare — până la 10 în total. După a zecea eșec, webhook-ul este dezactivat.
Returnează rapid 200, procesare asincronă
Confirmați cu 200 OK cât mai repede posibil, apoi procesează datele de încărcare în mod asincron printr-o sarcină de fundal sau o coadă. Un punct final lent poate fi considerat o eroare chiar dacă, în cele din urmă, operațiunea se finalizează cu succes.
Webhooks, răspunsuri
Cum pot verifica semnătura unui webhook Fabrixa?
Recalculează valoarea HMAC-SHA256 a corpului brut al cererii folosind cheia ta secretă, codifică rezultatul în format base64 și compară-l cu antetul x-webhook-signature folosind o comparație cu timp constant, cum ar fi hash_equals. Fabrixa oferă exemple concrete în PHP brut și Laravel, iar orice neconcordanță trebuie respinsă înainte ca încărcătura utilă să fie procesată.
Ce evenimente webhook transmite Fabrixa?
Fabrixa transmite două evenimente, identificate prin antetul x-webhook-topic: „order.created”, declanșat atunci când se plasează o comandă prin intermediul API sau direct în platformă, și „order.updated”, declanșat atunci când se modifică starea comenzii sau starea de îndeplinire a acesteia. Ambele evenimente conțin obiectul complet al comenzii, astfel încât un singur handler poate fi configurat pentru acest topic.
De câte ori încearcă Fabrixa să reexecute un webhook care a eșuat?
Fabrixa reîncearcă transmiterea unui webhook de până la 10 ori atunci când răspunsul nu este 2xx, 301 sau 302. Orice cod de stare 4xx, 5xx sau expirarea timpului de așteptare este considerată o eroare și declanșează o nouă încercare; după a zecea încercare eșuată, webhook-ul este dezactivat, astfel încât punctul final ar trebui să returneze rapid codul de stare 200 și să proceseze încărcătura în mod asincron.
Ce antete conține o cerere de tip webhook Fabrixa?
Fiecare cerere POST de tip webhook conține trei antete: „content-type”, care are întotdeauna valoarea „application/json”; „x-webhook-topic”, care denumește evenimentul, de exemplu „order.updated”; și „x-webhook-signature”, semnătura HMAC-SHA256 codificată în format base64 a corpului neprelucrat al cererii. Utilizați topic-ul pentru a direcționa evenimentul și semnătura pentru a-l verifica înainte de a accepta încrederea în conținutul mesajului.
Ce stări ale comenzii apar în conținutul unui webhook Fabrixa?
Payload-ul conține un câmp de stare cu patru valori — Finalizat, Anulat, În așteptare și Importat — și un câmp separat, fulfillment_status, cu cinci valori: Neîndeplinit, Îndeplinit parțial, Programat, Respingut și Îndeplinit. Un singur eveniment order.updated poate semnala o modificare în oricare dintre aceste câmpuri.
Configurează punctul final al webhook-ului.
Ghidul de integrare vă ghidează pas cu pas prin procesul de înregistrare a punctului dvs. terminal și prin gestionarea ciclului de viață al comenzii de la început până la sfârșit. Documentația completă API conține schema completă a încărcăturii utile.