Webhooks

Wenn eine App im Modus HIOBuy warehouse fulfillment läuft, sendet HIOBuy Fulfillment-Lebenszyklus-Ereignisse an Ihren HTTPS-Endpoint. Konfiguration unter Developer Portal → Webhooks . Die Zustellung ist asynchron; Public-API-Antworten warten nicht auf Ihren Webhook-Server.

Voraussetzung: Channel Auth → Fulfillment-Modus = HIOBuy warehouse. Im Self-Modus nur Intro sichtbar; Endpoint erstellen/aktivieren nicht möglich.

Überblick {#overview}

Registrierung, Secret-Rotation, Delivery-Historie und manueller Retry sind portal-only (Session-Auth). In v1 gibt es kein Public /v1/webhooks/*-Management-API.

Event-Katalog {#events}

Pro Endpoint abonnieren. Mindestens ein Event erforderlich.

Live-Push warehouse→Developer wird schrittweise ausgerollt; validieren Sie Ihren Empfänger heute mit Send test.

Öffentliches Envelope {#envelope}

Jeder Delivery-Body ist 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"
  }
}

Beispiel-data {#data-shapes}

Entspricht Portal-Testsamples; Live nutzt dieselben Keys.

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-Zustellung {#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…

• In Production muss die Endpoint-URL HTTPS sein. Außerhalb Production sind http://localhost / Tunnel erlaubt.
• Antworten Sie innerhalb von 10 s mit 2xx. Sonst Retry bis Exhaustion.
• Zustellung ist at-least-once. Deduplizieren Sie über id (optional HioBuy-Event-Id).

Signaturprüfung {#signature}

1. HioBuy-Signature lesen (t=<unix_seconds>,v1=<hex_hmac>).
2. Signaturpayload bauen: "{t}.{raw_body}" — raw_body ist der exakte Body (UTF-8-JSON wie empfangen).
3. HMAC-SHA256(secret, signed_payload) berechnen und hex-kodieren.
4. Mit v1 zeitkonstant vergleichen.
5. Ablehnen, wenn |now - t| zu groß (empfohlene Toleranz: 5 Minuten).

Node.js Beispiel

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_… nur serverseitig speichern. Portal zeigt Maskierung (letzte 6 Zeichen). Nach Rotation Server vor der nächsten Delivery aktualisieren.

Retries & Delivery-Status {#retries}

Nach dem letzten Fehlversuch Status failed. Im Portal Retry now möglich.

Status: pending · success · retrying · failed.

Portal-Ablauf {#portal}

1. App unter Channel Auth / Fulfillment-Setup auf warehouse fulfillment setzen.
2. Webhooks  öffnen → Add endpoint.
3. HTTPS-URL, optionale Beschreibung und Events wählen.
4. Signaturgeheimnis sofort kopieren (einmalig).
5. Send test event und Deliveries/Attempts prüfen.
6. Secret rotieren, deaktivieren oder löschen bei Bedarf.

Limits & Aufbewahrung {#limits}

Verwandt

• Fulfillment setup — Warehouse-Modus
• Fulfillment API — internationale Versandrouten
• Authentication — API-Keys (getrennt vom Webhook-Secret)
• Sandbox — Sandbox-Orders pushen nicht automatisch; Portal Send test nutzen