Webhooks

Lorsque l’app est en mode HIOBuy warehouse fulfillment, HIOBuy envoie des événements du cycle de vie fulfillment vers votre endpoint HTTPS. Configurez dans Developer Portal → Webhooks . La livraison est asynchrone ; les réponses Public API n’attendent pas votre serveur webhook.

Prérequis: Autorisation canal → mode fulfillment = HIOBuy warehouse. En mode self, intro visible seulement ; création/activation d’Endpoint impossibles.

Vue d’ensemble {#overview}

Inscription, rotation du secret, historique et retry manuel sont portail uniquement (auth session). Pas d’API Public /v1/webhooks/* en v1.

Catalogue d’événements {#events}

Abonnez-vous par endpoint. Au moins un événement requis.

Le push live warehouse→développeur est déployé progressivement ; validez votre récepteur via Send test dès maintenant.

Envelope public {#envelope}

Chaque corps de livraison est un 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"
  }
}

Exemples de data {#data-shapes}

Conformes aux échantillons de test portail ; le live utilise les mêmes clés.

procurement.failed

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

package.exception

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

shipment.ready_for_payment

{
  "shipment_id": "115",
  "order_sn": "JIYUNRI1349",
  "external_shipment_id": "MY-INTL-ORDER-001",
  "previous_status": "PENDING",
  "status": "WAIT_PAYMENT",
  "amount_due": {
    "amount": 10200,
    "currency": "CNY"
  },
  "source_packages": [
    {
      "package_id": "pkg_…",
      "external_order_id": "STORE-ORDER-10086"
    }
  ],
  "occurred_at": "2026-09-09T16:20:00.000Z"
}

shipment.dispatched

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

balance.low

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

Livraison 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…

• En production, l’URL doit être HTTPS. Hors production, http://localhost / tunnels peuvent être autorisés.
• Répondez 2xx en 10 s. Sinon retry jusqu’à épuisement.
• Livraison at-least-once. Dédupliquez sur id (et optionnellement HioBuy-Event-Id).

Vérification de signature {#signature}

1. Lire HioBuy-Signature (t=<unix_seconds>,v1=<hex_hmac>).
2. Construire "{t}.{raw_body}" où raw_body est le corps brut reçu (JSON UTF-8).
3. Calculer HMAC-SHA256(secret, signed_payload) en hex.
4. Comparer à v1 en temps constant.
5. Rejeter si |now - t| trop grand (tolérance recommandée : 5 minutes).

Node.js exemple

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

Stockez whsec_… uniquement côté serveur. Le portail masque (6 derniers caractères). Après rotation, mettez à jour le serveur avant la prochaine livraison.

Retries et statuts {#retries}

Après le dernier échec : failed. Retry now possible dans le détail portail.

Statuts : pending · success · retrying · failed.

Parcours portail {#portal}

1. Passez l’app en warehouse fulfillment via Channel Auth / setup.
2. Ouvrez Webhooks  → Add endpoint.
3. Saisissez l’URL HTTPS, une description optionnelle et les événements.
4. Copiez le secret dès l’affichage (une seule fois).
5. Utilisez Send test event et inspectez deliveries / attempts.
6. Faites pivoter le secret, désactivez ou supprimez si besoin.

Limites et rétention {#limits}

Voir aussi

• Fulfillment setup — mode warehouse
• Fulfillment API — expédition internationale
• Authentication — clés API (distinctes du secret webhook)
• Sandbox — les commandes sandbox ne poussent pas automatiquement ; utiliser Send test