Всяко събитие. Всеки полезен товар. Подписано.
Fabrixa изпраща събития, свързани с поръчки, към Вашия ендпойнт в реално време. Вашият сървър предоставя един публичен POST ендпойнт; ние изпращаме пълното тяло на поръчката с HMAC-SHA256 подпис и темата на събитието в заглавните редове. Проверете подписа, върнете бързо отговор 200 и обработете асинхронно.
Три заглавни заглавия идентифицират и удостоверяват заявката.
Всеки POST уебхук съдържа едни и същи три заглавни полета. Използвайте x-webhook-topic за да насочи събитието и x-webhook-signature за да го проверите, преди да се доверите на тази организация.
content-type е винаги application/json. x-webhook-signature е Base64-кодираният HMAC-SHA256 на необработеното тяло на съобщението. x-webhook-topic това е името на събитието.
{
"content-type": "application/json",
"x-webhook-topic": "order.updated",
"x-webhook-signature": "YmEwNjBhMGMy...MAxMw=="
}
Днес ще обсъдим две теми.
Всеки уебхук се задейства от конкретен 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 пъти. След десетия неуспешен опит уебхукът се деактивира.
Връщане на 200 бързо, обработка асинхронно
Потвърдете с 200 OK възможно най-бързо, след което обработете полезния товар асинхронно чрез задача на заден план или опашка. Бавната крайна точка може да се третира като грешка, дори ако в крайна сметка операцията приключи успешно.
Уебхукове, отговори
Как да проверя подписите на уебхуковете на Fabrixa?
Преизчислете HMAC-SHA256 на необработеното тяло на заявката, като използвате Вашия секретен ключ, кодирайте резултата в Base64 и го сравнете със заглавката „x-webhook-signature“ чрез сравнение с константно време, като например hash_equals. Fabrixa предоставя готови примери на чист PHP и Laravel, като всяко несъответствие трябва да бъде отхвърлено, преди полезният товар да бъде обработен.
Какви събития за уебхук изпраща Fabrixa?
Fabrixa изпраща две събития, идентифицирани чрез заглавката x-webhook-topic: order.created, което се задейства при подаване на поръчка чрез API или директно в платформата, и order.updated, което се задейства при промяна на статуса на поръчката или на статуса на изпълнението. И двете съдържат пълния обект на поръчката, така че един обработващ модул може да следи за тази тема.
Колко пъти Fabrixa прави повторен опит при неуспешен уебхук?
Fabrixa повтаря опита за доставка на уебхук до 10 пъти, когато отговорът не е 2xx, 301 или 302. Всеки код 4xx, 5xx или изтичане на времето се счита за неуспех и предизвиква повторен опит; след десетия неуспешен опит уебхукът се деактивира, затова крайната точка трябва бързо да върне код 200 и да обработи полезния товар асинхронно.
Какви заглавни редове съдържа заявката за уебхук Fabrixa?
Всеки POST уебхук съдържа три заглавия: content-type, винаги application/json; x-webhook-topic, което определя името на събитието, например order.updated; и x-webhook-signature, кодираният в base64 HMAC-SHA256 подпис на необработеното тяло на съобщението. Използвайте темата, за да насочите събитието, и подписа, за да го проверите, преди да се доверите на полезния товар.
Какви статуси на поръчки се появяват в полезния товар на уебхука на Fabrixa?
Полето „payload“ съдържа поле „status“ с четири стойности — „Completed“, „Canceled“, „On hold“ и „Imported“ — както и отделно поле „fulfillment_status“ с пет стойности: „Unfulfilled“, „Partially fulfilled“, „Scheduled“, „Rejected“ и „Fulfilled“. Едно събитие „order.updated“ може да сигнализира за промяна в което и да е от двете полета.
Настройте крайната точка на уебхука си.
Ръководството за интеграция Ви води стъпка по стъпка през процеса на регистриране на Вашия краен пункт и управление на целия цикъл на поръчката. Пълната справка за API съдържа цялостната схема на полезния товар.