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

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

Fabrixa надсилає події, пов’язані з замовленнями, на вашу endpoint в режимі реального часу. Ваш сервер надає доступ до однієї публічної endpoint POST; ми надсилаємо повний текст замовлення з підписом 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 спроб, після чого функція вимикається

A 2xx (наприклад, 200) або а 301 / 302 вважається успіхом. Будь-яке 4xx, 5xx або у разі перевищення ліміту часу відбувається повторна спроба — загалом до 10 разів. Після десятої невдалої спроби webhook деактивується.

Відповідь

Швидко повернути код 200, обробити асинхронно

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

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

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

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

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