Κάθε συμβάν. Κάθε ωφέλιμο φορτίο. Υπογεγραμμένο.
Το Fabrixa διαβιβάζει συμβάντα παραγγελιών στο τελικό σας σημείο σε πραγματικό χρόνο. Ο διακομιστής σας διαθέτει ένα δημόσιο τελικό σημείο POST· εμείς στέλνουμε το πλήρες κείμενο της παραγγελίας με υπογραφή HMAC-SHA256 και το θέμα του συμβάντος στις κεφαλίδες. Επαληθεύστε την υπογραφή, επιστρέψτε γρήγορα τον κωδικό κατάστασης 200 και επεξεργαστείτε την παραγγελία ασύγχρονα.
Τρεις κεφαλίδες προσδιορίζουν και επαληθεύουν το αίτημα.
Κάθε POST webhook περιλαμβάνει τις ίδιες τρεις κεφαλίδες. Χρησιμοποιήστε x-webhook-topic για να δρομολογήσει το συμβάν και x-webhook-signature για να το επαληθεύσετε πριν εμπιστευτείτε τον οργανισμό.
content-type είναι πάντα application/json. x-webhook-signature είναι το HMAC-SHA256 σε κωδικοποίηση base64 του ακατέργαστου σώματος. x-webhook-topic είναι το όνομα της εκδήλωσης.
{
"content-type": "application/json",
"x-webhook-topic": "order.updated",
"x-webhook-signature": "YmEwNjBhMGMy...MAxMw=="
}
Σήμερα θα συζητήσουμε δύο θέματα.
Κάθε webhook ενεργοποιείται από ένα συγκεκριμένο x-webhook-topic τιμή. Και τα δύο περιέχουν το πλήρες αντικείμενο της παραγγελίας, οπότε ένας μόνο χειριστής μπορεί να ενεργοποιηθεί στο θέμα.
Έχει υποβληθεί μια νέα παραγγελία.
Ενεργοποιείται όταν δημιουργείται μια παραγγελία στο Fabrixa — είτε μέσω αιτήματος API είτε απευθείας στην πλατφόρμα.
Μια υπάρχουσα παραγγελία αλλάζει.
Ενεργοποιείται όταν αλλάζουν τα στοιχεία της παραγγελίας — για παράδειγμα, όταν αλλάζει η κατάσταση της παραγγελίας ή η κατάσταση εκτέλεσης.
Τι μπορούν να δείξουν τα πεδία κατάστασης.
Το ωφέλιμο φορτίο μεταφέρει την παραγγελία status καθώς και ένα ξεχωριστό fulfillment_status. Ενεργοποιήστε τις για να καθορίσετε την κατάσταση της παραγγελίας σας.
- Completed — αποστάληκε ή παραλήφθηκε και επιβεβαιώθηκε η παραλαβή.
- Canceled — η πληρωμή ακυρώθηκε· η συναλλαγή δεν ολοκληρώθηκε.
- On hold — η παραγγελία έχει προσωρινά ανασταλεί.
- Imported — η παραγγελία εισήχθη στην πλατφόρμα.
- Unfulfilled — δεν έχει ακόμη ετοιμαστεί ή αποσταλεί.
- Partially fulfilled — ορισμένα προϊόντα έχουν ήδη υποβληθεί σε επεξεργασία ή αποσταλεί, ενώ άλλα βρίσκονται σε αναμονή.
- Scheduled — έχουν προγραμματιστεί και έχει καθοριστεί το χρονοδιάγραμμα επεξεργασίας τους.
- Rejected — το αίτημα εκπλήρωσης απορρίφθηκε.
- Fulfilled — έχουν υποστεί πλήρη επεξεργασία και έχουν παραδοθεί ή τεθεί στη διάθεση του πελάτη.
Πώς μοιάζει το σώμα.
Το πλήρες order.updated το ωφέλιμο φορτίο, ακριβώς όπως το τεκμηριώνει το έγγραφο αναφοράς API — η παραγγελία, οι καταστάσεις της, καθώς και οι σειρές με τις λεπτομέρειες σχετικά με τις παραλλαγές, τα προϊόντα και τις πηγές.
{
"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" }
}
]
}
]
}
Υπολογίστε εκ νέου το HMAC, συγκρίνετε τα αποτελέσματα και, στη συνέχεια, θεωρήστε αξιόπιστο το κύριο μέρος του μηνύματος.
Υπολογίστε εκ νέου το HMAC-SHA256 του ακατέργαστου περιεχομένου του αιτήματος χρησιμοποιώντας το μυστικό κλειδί σας, κωδικοποιήστε το σε base64 και συγκρίνετέ το με x-webhook-signature. Χρησιμοποιείτε πάντα σύγκριση σταθερού χρόνου (hash_equals) για την αποφυγή επιθέσεων χρονισμού.
$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…
}
Επανειλημμένες προσπάθειες και η απάντηση που αναμένουμε.
Έως 10 προσπάθειες, μετά απενεργοποιείται
Οποιοδήποτε 2xx η απόκριση (π.χ. 200) θεωρείται επιτυχής, όπως και μια 301 ή 302 ανακατεύθυνση. Οποιαδήποτε 4xx, 5xx ή η λήξη του χρονικού ορίου ενεργοποιεί μια νέα προσπάθεια — έως και 10 συνολικά. Μετά τη δέκατη αποτυχία, το webhook απενεργοποιείται.
Γρήγορη επιστροφή 200, ασύγχρονη επεξεργασία
Αναγνωρίστε με 200 OK όσο το δυνατόν γρηγορότερα και, στη συνέχεια, να επεξεργαστείτε το ωφέλιμο φορτίο ασύγχρονα μέσω μιας εργασίας στο παρασκήνιο ή μιας ουράς. Ένα αργό σημείο τερματισμού μπορεί να θεωρηθεί ως αποτυχία, ακόμη και αν τελικά ολοκληρωθεί με επιτυχία.
Webhooks, απαντήσεις
Πώς μπορώ να επαληθεύσω την υπογραφή ενός webhook Fabrixa;
Υπολογίστε εκ νέου το HMAC-SHA256 του ακατέργαστου σώματος του αιτήματος χρησιμοποιώντας το μυστικό κλειδί σας, κωδικοποιήστε το αποτέλεσμα σε base64 και συγκρίνετέ το με την κεφαλίδα x-webhook-signature χρησιμοποιώντας μια μέθοδο σύγκρισης σταθερού χρόνου, όπως η hash_equals. Το Fabrixa παρέχει πρακτικά παραδείγματα σε καθαρό PHP και Laravel, και οποιαδήποτε αναντιστοιχία θα πρέπει να απορρίπτεται πριν από την επεξεργασία του ωφέλιμου φορτίου.
Ποια συμβάντα webhook στέλνει το Fabrixa;
Το Fabrixa αποστέλλει δύο συμβάντα, τα οποία προσδιορίζονται από την κεφαλίδα x-webhook-topic: το «order.created», το οποίο ενεργοποιείται όταν υποβάλλεται μια παραγγελία μέσω του API ή απευθείας στην πλατφόρμα, και το «order.updated», το οποίο ενεργοποιείται όταν αλλάζει η κατάσταση της παραγγελίας ή η κατάσταση εκτέλεσής της. Και τα δύο μεταφέρουν το πλήρες αντικείμενο της παραγγελίας, οπότε ένας χειριστής μπορεί να ενεργοποιηθεί βάσει του θέματος.
Πόσες φορές το Fabrixa επαναλαμβάνει την προσπάθεια για ένα webhook που απέτυχε;
Το Fabrixa επαναλαμβάνει την αποστολή ενός webhook έως και 10 φορές, όταν η απόκριση δεν είναι 2xx, 301 ή 302. Οποιοδήποτε κωδικός 4xx, 5xx ή λήξη χρόνου αναμονής θεωρείται αποτυχία και ενεργοποιεί μια νέα προσπάθεια· μετά τη δέκατη αποτυχημένη προσπάθεια, το webhook απενεργοποιείται, οπότε το endpoint θα πρέπει να επιστρέψει γρήγορα τον κωδικό 200 και να επεξεργαστεί το payload ασύγχρονα.
Ποια κεφαλίδες περιλαμβάνει ένα αίτημα webhook τύπου Fabrixa;
Κάθε αίτημα POST webhook περιλαμβάνει τρεις κεφαλίδες: content-type, πάντα application/json· x-webhook-topic, που ονομάζει το συμβάν, όπως order.updated· και x-webhook-signature, την κωδικοποιημένη σε base64 υπογραφή HMAC-SHA256 του ακατέργαστου σώματος. Χρησιμοποιήστε το θέμα για τη δρομολόγηση του συμβάντος και την υπογραφή για την επαλήθευσή του πριν εμπιστευτείτε το ωφέλιμο φορτίο.
Ποιες καταστάσεις παραγγελιών εμφανίζονται στο περιεχόμενο ενός webhook Fabrixa;
Το payload περιλαμβάνει ένα πεδίο κατάστασης με τέσσερις τιμές — «Ολοκληρώθηκε», «Ακυρώθηκε», «Σε αναμονή» και «Εισήχθη» — καθώς και ένα ξεχωριστό πεδίο fulfillment_status με πέντε τιμές: «Δεν έχει εκτελεστεί», «Εκτελέστηκε εν μέρει», «Προγραμματισμένο», «Απορρίφθηκε» και «Εκτελέστηκε». Ένα μεμονωμένο συμβάν order.updated μπορεί να αναφέρει αλλαγή σε οποιοδήποτε από τα δύο πεδία.
Συνδέστε το σημείο τερματισμού του webhook σας.
Ο οδηγός ενσωμάτωσης σας καθοδηγεί βήμα προς βήμα στην εγγραφή του τερματικού σας και στη διαχείριση του κύκλου ζωής μιας παραγγελίας από την αρχή έως το τέλος. Η πλήρης τεκμηρίωση του API περιλαμβάνει το πλήρες σχήμα του ωφέλιμου φορτίου.