Вебхуки

Когда приложение в режиме HIOBuy warehouse fulfillment, HIOBuy отправляет события жизненного цикла fulfillment на ваш HTTPS endpoint. Настройте в Developer Portal → Webhooks . Доставка асинхронна; ответы Public API не ждут ваш webhook-сервер.

Требование: Авторизация каналов → режим fulfillment = HIOBuy warehouse. В self-режиме виден только intro; создать/включить Endpoint нельзя.

Обзор {#overview}

Регистрация, ротация секрета, история доставок и ручной retry — только в портале (сессионная авторизация). В v1 нет Public API /v1/webhooks/*.

Каталог событий {#events}

Подписка на endpoint. Нужно ≥ 1 событие.

Live-пуш warehouse→developer внедряется поэтапно; сейчас проверяйте приёмник через Send test в портале.

Публичный envelope {#envelope}

Тело каждой доставки — JSON:

{
  "id": "evt_01HXYZ…",
  "type": "package.received",
  "created_at": "2026-08-16T04:00:00.000Z",
  "livemode": true,
  "app_id": "app_…",
  "data": {
    "package_id": "pkg_…",
    "order_id": "ord_…",
    "status": "received"
  }
}

Примеры data {#data-shapes}

Ниже — тестовые сэмплы портала; live использует те же ключи.

procurement.failed

{
  "order_id": "ord_…",
  "status": "failed",
  "reason": "supplier_rejected"
}

package.exception

{
  "package_id": "pkg_…",
  "order_id": "ord_…",
  "status": "exception",
  "exception_type": "DAMAGED"
}

shipment.dispatched

{
  "shipment_id": "shp_…",
  "tracking_number": "…",
  "status": "dispatched"
}

balance.low

{
  "available_amount": 12.5,
  "currency": "USD",
  "threshold": 50
}

HTTP-доставка {#delivery}

POST /your/webhook-path HTTP/1.1
Host: your-server.example
Content-Type: application/json
User-Agent: HioBuy-Webhooks/1.0
HioBuy-Event-Id: evt_01HXYZ…
HioBuy-Signature: t=1723780800,v1=abcdef0123456789…

• В production URL должен быть HTTPS. Вне production допускаются http://localhost / туннели.
• Ответьте 2xx за 10 с. Иначе — retry до исчерпания попыток.
• Доставка at-least-once. Дедуплицируйте по id (и опционально HioBuy-Event-Id).

Проверка подписи {#signature}

1. Прочитайте HioBuy-Signature (t=<unix_seconds>,v1=<hex_hmac>).
2. Соберите строку: "{t}.{raw_body}", где raw_body — сырое тело (UTF-8 JSON как пришло).
3. Вычислите HMAC-SHA256(secret, signed_payload) и hex.
4. Сравните с v1 за постоянное время.
5. Отклоните при слишком большом |now - t| (рекомендуемый допуск: 5 минут).

Node.js пример

import crypto from "node:crypto";
 
function verifyHioBuySignature(rawBody, signatureHeader, secret, toleranceSec = 300) {
  const match = /^t=(\d+),v1=([0-9a-f]+)$/i.exec(signatureHeader || "");
  if (!match) return false;
 
  const t = Number(match[1]);
  const expected = match[2].toLowerCase();
  if (!Number.isFinite(t)) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > toleranceSec) return false;
 
  const signed = `${t}.${rawBody}`;
  const digest = crypto
    .createHmac("sha256", secret)
    .update(signed, "utf8")
    .digest("hex");
 
  const a = Buffer.from(digest, "utf8");
  const b = Buffer.from(expected, "utf8");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Храните whsec_… только на сервере. В портале — маска (последние 6 символов). После ротации обновите сервер до следующей доставки.

Повторы и статусы {#retries}

После последней ошибки статус failed. В деталях доставки можно Retry now.

Статусы: pending · success · retrying · failed.

Сценарий в портале {#portal}

1. В Channel Auth / fulfillment setup включите warehouse fulfillment.
2. Откройте Webhooks  → Add endpoint.
3. Укажите HTTPS URL, описание и события.
4. Сразу скопируйте секрет (показывается один раз).
5. Отправьте test event и проверьте deliveries / attempts.
6. При необходимости ротируйте секрет, отключите или удалите endpoint.

Лимиты и хранение {#limits}

Связанные разделы

• Fulfillment setup — режим warehouse
• Fulfillment API — международная отправка
• Authentication — API keys (не секрет webhook)
• Sandbox — заказы sandbox не пушат автоматически; используйте Send test