РОЗРОБНИКИ - ПОСИЛАННЯ НА ВЕБ-ХУКИ

Замовляйте події життєвого циклу, підписані та захищені від повторних спроб.

Вебхуки спрацьовують при кожному переході стану замовлення: отримано, надруковано, відправлено, не виконано. JSON через HTTPS, підписаний HMAC-SHA256 для перевірки, черга повторних спроб з експоненціальним з експоненціальним відступом до 24 годин. Посилання на подію, приклади коду перевірки підпису та політика повторних спроб/відмов нижче.

Посібник з інтеграції → Запустити тестову подію

HMAC-SHA256 ПІДПИСАНО - ЩОНАЙМЕНШЕ ОДИН РАЗ - 24 години ПОВТОРНА ПОДАЧА - ЧЕРГА МЕРТВИХ ЛИСТІВ

ТИПИ ПОДІЙ

П'ять подій життєвого циклу замовлення.

Підпишіться на будь-яку підгрупу на сайті PUT /v1/account/webhook кінцева точка. Більшість інтеграцій підписуються на всі п'ять.

Подія	Стріляє, коли	Типова дія
замовлення.отримано	Fabrixa прийняв замовлення і призначив `order_id`. Відповідайте протягом декількох секунд після POST.	Оновлення статусу внутрішнього замовлення до "у виробництві"; поверхня для кінцевого споживача.
order.printed	Етап реактивного друку завершено. Виріб переходить до розкрою та пошиття. Середній етап виробництва.	Необов'язково - деякі команди використовують цю функцію для імейлів "Ваше замовлення готується до відправки".
замовлення.відправлено	Перевірено якість, упаковано, передано перевізнику. Видано номер для відстеження.	Оновлення статусу замовлення до "відправлено"; сповіщення кінцевого клієнта про відправлення з URL-адресою для відстеження.
замовлення.доставлено	Перевізник підтвердив доставку на адресу отримувача.	Запустіть потоки після покупки: запит на рецензію, супутні товари тощо.
order.failed.	Замовлення не може бути виконане - малюнок недоступний, адреса одержувача невірна, тканина відсутня на складі протягом тривалого періоду.	Відкрити тікет / повідомити операторів. Корисне навантаження включає в себе `error.code` для логіки увімкнення.

ФОРМА ЗАРПЛАТИ

Той самий конверт, дані для конкретної події.

Загальний конверт (event, order_id, order_ref, timestamp) плюс специфічний для події дані об'єкт. Спочатку споживайте конверт; увімкніть подія для форми даних.

замовлення.відправлено

# order.dispatched корисне навантаження - POST на вашу URL-адресу веб-хука

НАДІСЛАТИ /your-webhook-endpoint
Тип вмісту: application/json
X-Fabrixa-Event: order.dispatched
X-Fabrixa-Signaturet=1715173928,v1=ab3c4...
X-Fabrixa-Delivery-Id: del_94kQ7r2L

{
  "подія":        "order.dispatched",
  "order_id":     "ord_8e6f4b2a",
  "order_ref":    "shopify-1042",
  "timestamp":    "2026-05-15T11:32:08Z",
  "production_hub": "ПТ",
  "дані": {
    "відстеження": {
      "перевізник":         "DHL",
      "номер_відстеження": "JJD0123456789",
      "tracking_url":    "https://dhl.com/track/JJD0123456789",
      "estimated_delivery": "2026-05-19"
    },
    "одержувач": {
      "ім'я":    "Лєна Коста",
      "місто":    "Порту",
      "країна": "ПТ"
    }
  }
}

ПЕРЕВІРКА ПІДПИСУ

HMAC-SHA256 закінчено (мітка часу + необроблене тіло).

Перевірте підпис перед обробкою. Скористайтеся кнопкою сире тіло запиту - а не повторно серіалізований JSON-об'єкт - інакше HMAC не збігатиметься. Секрет підпису видається один раз, коли ви налаштовуєте URL-адресу веб-хука; змінюйте його за допомогою панелі інструментів.

verify-signature.js

// Node.js / Експрес-приклад
const crypto = вимагати("крипто");

app.пост("/webhook", Експрес.сирий({ type: "application/json" }), (req, res) => { }), (req, res) => {
  const signature = req.headers["x-fabrixa-signature"];
  const [tPart, v1Part] = signature.розкол(",");
  const timestamp = tPart.розкол("=")[1];
  const received = v1Part.розкол("=")[1];

  // Відхиляти події, старші за 5 хвилин (захист від повторів)
  якщо (Математика.прес(Дата.Зараз.() / 1000 - мітка часу) > 300) повернення Res.статус(400).кінець();

  const payload = `${timestamp}.${req.body.toString()}`;
  const expected = crypto
    .createHmac("sha256", process.env.FABRIXA_WEBHOOK_SECRET)
    .оновлення(корисне навантаження)
    .дайджест("hex" - "прокляття");

  якщо (Крипто.timingSafeEqual(Буфер.від(отримано), Буфер.від(очікувано))) {
    повернення Res.статус(401).кінець();
  }

  // Підпис дійсний - обробити подію
  const event = JSON.розбір(req.body);
  handleEvent(event);
  res.статус(200).кінець();
});

Еквівалентні приклади для Python (Flask), PHP, Ruby та Go знаходяться у теці скриптів колекції Postman. timingSafeEqual не використовуйте рівність рядків, вона вразлива до атак на синхронізацію.

ПОЛІТИКА ПОВЕРНЕННЯ

Експоненціальний відступ до 24 годин.

Веб-хук доставляється щонайменше один раз. Якщо ваша кінцева точка повертає 5xx або таймаут (таймаут на 10 секунд), ми повторюємо спробу за експоненціальним графіком протягом 24 годин. Після 24 годин невдалої спроби подія потрапляє до черги "мертвих літер", яку ви можете відтворити вручну.

НЕГАЙНО

Початкова доставка + повторна спроба 1

Перша доставка на подію. Якщо 5xx або таймаут, повторити спробу через 30 секунд.

ЗАДНІЙ ХІД

Спроби 2-8, експоненціальна

60с → 5хв → 30хв → 2год → 6год → 12год → 24год. Кожна повторна спроба чекає довше.

МЕРТВА ЛІТЕРАТУРА

Через 24 години після відмови

Подію перенесено до черги мертвих літер. Повторіть вручну через інформаційну панель або POST /v1/webhooks/replay/:delivery_id.

ORDER.FAILED EVENT

Структуровані причини помилок для логіки увімкнення.

Найбільш оперативно важлива подія. Корисне навантаження включає в себе стабільну error.code string - безпечно вмикати для автоматизованої маршрутизації, створення тікетів або обміну повідомленнями з кінцевим клієнтом.

order.failed.

{
  "подія":     "order.failed",
  "order_id":  "ord_8e6f4b2a",
  "order_ref": "shopify-1042",
  "timestamp": "2026-05-13T09:14:22Z",
  "дані": {
    "помилка": {
      "код":    "artwork_unreachable",
      "повідомлення": "GET on artwork_url failed (timeout 30s) after 3 attempts",
      "повторна спроба": правда,
      "контекст": {
        "url_твору_мистецтва": "https://cdn.yourbrand.com/art/drop-001.png"
      }
    }
  }
}

# Загальні значення коду помилки:
# artwork_unreachable - ваша URL-адреса ілюстрації не відповідає
# artwork_invalid_format - не вдалося розібрати файл (спробуйте PNG / векторний PDF)
# роздільна здатність зображення_низька - DPI занадто низька для обраного товару
# address_invalid - адреса отримувача не підтверджена
# fabric_unavailable - основа тканини відсутня на складі більше 7 днів
# метод_платежу_неуспішний - відхилено білінг по файлу
# compliance_flag - замовлення позначене перевіркою відповідності

ТЕСТУВАННЯ

Запускати вибіркові події без реальних замовлень.

POST /v1/webhooks/test надсилає синтетичну подію будь-якого типу на вашу зареєстровану URL-адресу веб-хука. Корисно для тестування вашого обробника перед розміщенням реальних замовлень або для перевірки нової кінцевої точки після розгортання.

Веб-хуки пісочниці перенаправляють на URL-адресу вашої пісочниці. Використовуйте інструмент тунелювання (ngrok, Cloudflare Tunnel), щоб спрямувати веб-хуки пісочниці на localhost під час розробки.

POST /v1/webhooks/test

скручуватися -X POST $BASE_URL/v1/webhooks/test \
  -H "Авторизація: Пред'явник $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "подія": "order.dispatched",
    "sample_order_id": "зразок"
  }'

# 200 OK
{
  "delivery_id": "del_test_94kQ",
  "posted_to":   "https://your-tunnel.ngrok.io/webhook",
  "статус":      "в черзі"
}

ЗАРЕЄСТРУЙТЕ СВІЙ ВЕБ-ХУК

Встановіть URL-адресу один раз. Ми подбаємо про доставку.

Одна URL-адреса веб-хука для кожного акаунта, на неї потрапляють усі типи подій. Фільтр на сторінці подія у вашому обробнику. Налаштуйте за допомогою посібника з інтеграції.

Посібник з інтеграції Поговоріть з інженером з розробки рішень

Довідник вебхуків