Розробники · Довідка щодо webhooks

Кожна подія. Кожен payload. Підписано.

Fabrixa надсилає події, пов’язані з замовленнями, на ваш endpoint в режимі реального часу. Ваш сервер надає доступ до одного публічного POST endpoint; ми надсилаємо повний текст замовлення з підписом HMAC-SHA256 та темою події в заголовках. Перевірте підпис, швидко поверніть код 200 та обробіть асинхронно.

Ознайомтеся з посібником з інтеграції → Повне посилання на API

HMAC-SHA256 · order.created / order.updated · 10 спроб доставки

Заголовки запиту

Три заголовки слугують для ідентифікації та перевірки запиту.

Кожен 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=="
}

Події webhooks

Сьогодні дві теми.

Кожен webhook запускається певним x-webhook-topic значенням. Обидва містять повний об’єкт замовлення, тому один обробник може розгалужувати логіку за темою.

order.created

Оформлено нове замовлення.

Запускається при створенні замовлення в Fabrixa — як через запит API, так і безпосередньо на платформі.

order.updated

Існуюче замовлення змінюється.

Спрацьовує при зміні деталей замовлення — наприклад, при зміні статусу замовлення або статусу виконання.

Статуси

Що можуть означати поля статусу.

Корисне навантаження несе замовлення status а також окремий fulfillment_status. Розгалужуйте логіку за цими полями, щоб керувати власним станом замовлення.

Статуси замовлень

Completed — відправлено або отримано, а отримання підтверджено.
Canceled — платіж було скасовано; транзакція не відбулася.
On hold — замовлення тимчасово заблоковано.
Imported — замовлення було імпортовано на платформу.

Статуси виконання замовлення

Unfulfilled — ще не підготовлено або не надіслано.
Partially fulfilled — деякі товари вже оброблено або відправлено, інші — ще в процесі обробки.
Scheduled — заплановано та включено до графіка обробки.
Rejected — запит на виконання було відхилено.
Fulfilled — повністю оброблені та доставлені або надані у розпорядження.

Payload

Як виглядає цей пристрій.

Повний order.updated payload, точно так, як це описано в довідковій документації API — замовлення, його статуси, а також рядки з детальною інформацією про варіант, товар та джерело.

Тіло POST — order.updated

{
  "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) щоб уникнути атак на основі часу.

Чистий PHP

$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');
}

Laravel

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 якнайшвидше, а потім обробити payload асинхронно за допомогою фонового завдання або черги. Повільну endpoint можна розглядати як збій, навіть якщо в результаті операція все-таки завершиться успішно.

Часті запитання

webhooks, відповіді

Як перевірити підпис webhook Fabrixa?

Перерахуйте HMAC-SHA256 необробленого тіла запиту, використовуючи свій секретний ключ, закодуйте результат у форматі base64 та порівняйте його з заголовком x-webhook-signature за допомогою функції порівняння з постійним часом, наприклад hash_equals. Fabrixa надає готові приклади на чистому PHP та Laravel, і будь-яка невідповідність повинна бути відхилена до обробки payload.

Які події webhooks надсилає 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 необробленого тіла запиту. Використовуйте тему для маршрутизації події, а підпис — для її перевірки, перш ніж довіряти payload.

Які статуси замовлень відображаються у payload webhook Fabrixa?

Дані payload містять поле status із чотирма значеннями — «Завершено», «Скасовано», «У стані очікування» та «Імпортовано» — а також окреме поле fulfillment_status із п’ятьма значеннями: «Не виконано», «Частково виконано», «Заплановано», «Відхилено» та «Виконано». Одне подія order.updated може повідомляти про зміну в будь-якому з цих полів.

Створіть свій обробник

Налаштуйте endpoint webhook.

У посібнику з інтеграції детально описано процес реєстрації вашого кінцевого пристрою та супровід життєвого циклу замовлення від початку до кінця. У повному довіднику API наведено повну схему payload.

Прочитайте посібник з інтеграції Повне посилання на API