Zum Inhalt springen
Garanify

Webhooks

Garanify meldet Ihrem Server, wenn ein Produkt kein gültiges Etikett zeigen kann oder sich der Tarif ändert. Jede Zustellung ist signiert, wird gespeichert und lässt sich erneut senden.

Die API ist gebaut und getestet. Das Hosting unter api.garanify.com ist in Vorbereitung; bis dahin läuft sie lokal. Schlüssel gibt es auf Anfrage.

Endpunkt einrichten

Ein Shop hat einen Webhook-Endpunkt. PUT …/webhook setzt URL und abonnierte Ereignisse und gibt beim ersten Mal das Signatur-Secret whsec_… zurück, nur dieses eine Mal. Mit rotateSecret: true bekommen Sie ein neues.

curl -X PUT "https://api.garanify.com/v1/shops/shp_4kq8Zt2mWc9x/webhook" \
  -H "Authorization: Bearer $GARANIFY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://mein-shop.example/hooks/garanify","events":["product.invalid","license.changed"]}'
import { Garanify } from '@garanify/sdk';

const garanify = new Garanify({ apiKey: process.env.GARANIFY_SECRET_KEY });
const endpoint = await garanify.webhooks.set({
  url: 'https://mein-shop.example/hooks/garanify',
  events: [
    'product.invalid',
    'license.changed'
  ]
});
<?php
// composer require garanify/sdk guzzlehttp/guzzle
$factory = new GuzzleHttp\Psr7\HttpFactory();
$garanify = new Garanify\Garanify(getenv('GARANIFY_SECRET_KEY'), ['httpClient' => new GuzzleHttp\Client(), 'requestFactory' => $factory, 'streamFactory' => $factory]);
$endpoint = $garanify->webhooks->set([
    'url' => 'https://mein-shop.example/hooks/garanify',
    'events' => [
        'product.invalid',
        'license.changed',
    ],
]);
import os, requests

res = requests.put(
    "https://api.garanify.com/v1/shops/shp_4kq8Zt2mWc9x/webhook",
    headers={"Authorization": f"Bearer {os.environ['GARANIFY_SECRET_KEY']}"},
    json={
        "url": "https://mein-shop.example/hooks/garanify",
        "events": [
            "product.invalid",
            "license.changed",
        ],
    },
    timeout=10,
)
res.raise_for_status()
data = res.json()
  • Nur https auf einem öffentlichen Hostnamen. IP-Adressen, localhost, .local, .internal und Zugangsdaten in der URL lehnen wir ab (webhook_url_invalid).
  • Löst der Hostname bei der Zustellung auf eine nicht öffentliche Adresse auf, stellen wir nicht zu (Ergebnis unreachable). Weiterleitungen folgen wir nicht.

Ereignisse

Jedes Ereignis hat id, type, createdAt, shop, livemode und data. Die Liste mit Beispielen liefert auch GET /v1/webhook-events. Neue Ereignistypen können dazukommen; ignorieren Sie unbekannte.

product.invalid

Ein Produkt hat Garantiedaten, die sich nicht zeigen lassen (z. B. Modell fehlt). In data: sku und errors.

{
  "id": "evt_3Hk9Lm2Pq7Rs",
  "type": "product.invalid",
  "createdAt": "2026-11-18T10:00:00Z",
  "shop": "shp_4kq8Zt2mWc9x",
  "livemode": true,
  "data": {
    "sku": "WAN28200",
    "errors": [
      {
        "code": "model_missing",
        "message": "The model identifier is missing."
      }
    ]
  }
}

license.changed

Tarif oder Lizenzstatus des Shops haben sich geändert. In data: from, to und state.

{
  "id": "evt_8Nb4Vc1Xz6Qw",
  "type": "license.changed",
  "createdAt": "2026-11-18T10:00:00Z",
  "shop": "shp_4kq8Zt2mWc9x",
  "livemode": true,
  "data": {
    "from": "free",
    "to": "pro",
    "state": "active"
  }
}

webhook.testnur auf Anfrage

Test-Ereignis, nur auf Anfrage über POST …/webhook/test. Nicht abonnierbar.

{
  "id": "evt_2Wd8Kp4Rt6Yn",
  "type": "webhook.test",
  "createdAt": "2026-11-18T10:00:00Z",
  "shop": "shp_4kq8Zt2mWc9x",
  "livemode": true,
  "data": {
    "message": "Test event from Garanify. Your endpoint verified the signature if you see this in your logs."
  }
}

Signatur

Jede Zustellung trägt den Header Garanify-Signature: t=<Unix-Sekunden>,v1=<hex>. v1 ist HMAC-SHA256 über <t>.<roher Body>, Schlüssel ist das Secret whsec_… als UTF-8. Garanify-Webhook-Id enthält die Ereignis-ID.

Zustellung
POST /hooks/garanify HTTP/1.1
Content-Type: application/json
User-Agent: Garanify-Webhooks/1
Garanify-Signature: t=1795000000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
Garanify-Webhook-Id: evt_3Hk9Lm2Pq7Rs

{"id":"evt_3Hk9Lm2Pq7Rs","type":"product.invalid","createdAt":"2026-11-18T10:00:00Z","shop":"shp_4kq8Zt2mWc9x","livemode":true,"data":{…}}

Signatur prüfen

  1. Den rohen Body lesen, bevor ein Framework ihn als JSON parst.
  2. t und alle v1 aus dem Header lesen. Liegt t mehr als 300 Sekunden von jetzt entfernt, ablehnen (Schutz vor Wiedereinspielen).
  3. HMAC-SHA256 berechnen und in konstanter Zeit vergleichen.
  4. Mit 2xx antworten, innerhalb von 5 Sekunden. Langsame Arbeit in eine Warteschlange legen.
# Signatur von Hand nachrechnen (OpenSSL)
t=1795000000
printf '%s.%s' "$t" "$(cat body.json)" | openssl dgst -sha256 -hmac "$GARANIFY_WEBHOOK_SECRET" -hex
import { createServer } from 'node:http';
import { verifyWebhook, WebhookVerificationError } from '@garanify/sdk';

createServer(async (req, res) => {
  const chunks = [];
  for await (const c of req) chunks.push(c);
  const raw = Buffer.concat(chunks); // roher Body, nicht vorher JSON.parse
  try {
    const event = await verifyWebhook(raw, req.headers['garanify-signature'], process.env.GARANIFY_WEBHOOK_SECRET);
    if (event.type === 'product.invalid') console.log(event.data.sku);
    res.writeHead(200).end();
  } catch (e) {
    res.writeHead(e instanceof WebhookVerificationError ? 400 : 500).end();
  }
}).listen(3000);
<?php
use Garanify\Webhook;
use Garanify\WebhookVerificationException;

$raw = file_get_contents('php://input'); // roher Body
try {
    $event = Webhook::verify($raw, $_SERVER['HTTP_GARANIFY_SIGNATURE'] ?? null, getenv('GARANIFY_WEBHOOK_SECRET'));
} catch (WebhookVerificationException $e) {
    http_response_code(400);
    exit;
}
if ($event['type'] === 'product.invalid') {
    error_log($event['data']['sku']);
}
http_response_code(200);
import hashlib, hmac, time

def verify(raw: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    t = int(parts.get("t", "0"))
    if abs(time.time() - t) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Ein vollständiger Empfänger liegt in examples/node-webhook, die PHP-Variante in examples/php/webhook.php.

Zustellung und Wiederholung

  • Bis zu drei Versuche: sofort, nach 10 Sekunden und nach weiteren 60 Sekunden. Jeder Versuch wartet höchstens 5 Sekunden.
  • Ergebnis je Zustellung: delivered (2xx), rejected (anderer Status), unreachable (keine Verbindung, Zeitüberschreitung, nicht öffentliche Adresse) oder pending. Den genauen HTTP-Status Ihres Endpunkts zeigen wir nicht.
  • lastDelivery am Endpunkt (GET …/webhook) zeigt { at, ok, outcome } der letzten Zustellung.
  • Ereignisse können mehrfach ankommen, etwa nach einem erneuten Senden. Entdoppeln Sie über id.
  • Die Reihenfolge ist nicht garantiert. Nutzen Sie createdAt oder lesen Sie den aktuellen Stand über die API nach.

Zustellungen ansehen und erneut senden

Wir speichern Zustellungen 30 Tage. Liste mit Cursor, neueste zuerst; erneut senden schickt denselben Body mit derselben Ereignis-ID an die aktuelle URL, signiert mit dem aktuellen Secret.

curl "https://api.garanify.com/v1/shops/shp_4kq8Zt2mWc9x/webhook/deliveries" \
  -H "Authorization: Bearer $GARANIFY_SECRET_KEY"
import { Garanify } from '@garanify/sdk';

const garanify = new Garanify({ apiKey: process.env.GARANIFY_SECRET_KEY });
const deliveries = await garanify.webhooks.deliveries({
  limit: 20
});
<?php
// composer require garanify/sdk guzzlehttp/guzzle
$factory = new GuzzleHttp\Psr7\HttpFactory();
$garanify = new Garanify\Garanify(getenv('GARANIFY_SECRET_KEY'), ['httpClient' => new GuzzleHttp\Client(), 'requestFactory' => $factory, 'streamFactory' => $factory]);
$deliveries = $garanify->webhooks->deliveries([
    'limit' => 20,
]);
import os, requests

res = requests.get(
    "https://api.garanify.com/v1/shops/shp_4kq8Zt2mWc9x/webhook/deliveries",
    headers={"Authorization": f"Bearer {os.environ['GARANIFY_SECRET_KEY']}"},
    timeout=10,
)
res.raise_for_status()
data = res.json()
curl -X POST "https://api.garanify.com/v1/shops/shp_4kq8Zt2mWc9x/webhook/deliveries/whd_6Tq2Lm9Xc4Vb/retry" \
  -H "Authorization: Bearer $GARANIFY_SECRET_KEY"
import { Garanify } from '@garanify/sdk';

const garanify = new Garanify({ apiKey: process.env.GARANIFY_SECRET_KEY });
const delivery = await garanify.webhooks.retry('whd_6Tq2Lm9Xc4Vb');
<?php
// composer require garanify/sdk guzzlehttp/guzzle
$factory = new GuzzleHttp\Psr7\HttpFactory();
$garanify = new Garanify\Garanify(getenv('GARANIFY_SECRET_KEY'), ['httpClient' => new GuzzleHttp\Client(), 'requestFactory' => $factory, 'streamFactory' => $factory]);
$delivery = $garanify->webhooks->retry('whd_6Tq2Lm9Xc4Vb');
import os, requests

res = requests.post(
    "https://api.garanify.com/v1/shops/shp_4kq8Zt2mWc9x/webhook/deliveries/whd_6Tq2Lm9Xc4Vb/retry",
    headers={"Authorization": f"Bearer {os.environ['GARANIFY_SECRET_KEY']}"},
    timeout=10,
)
res.raise_for_status()
data = res.json()

Testen

POST …/webhook/test sendet ein signiertes webhook.test-Ereignis, auch wenn Sie es nicht abonniert haben. Für lokale Tests ohne öffentliche URL bauen signWebhook() (Node.js) und Webhook::sign() (PHP) gültige Header.

curl -X POST "https://api.garanify.com/v1/shops/shp_4kq8Zt2mWc9x/webhook/test" \
  -H "Authorization: Bearer $GARANIFY_SECRET_KEY"
import { Garanify } from '@garanify/sdk';

const garanify = new Garanify({ apiKey: process.env.GARANIFY_SECRET_KEY });
const delivery = await garanify.webhooks.test();
<?php
// composer require garanify/sdk guzzlehttp/guzzle
$factory = new GuzzleHttp\Psr7\HttpFactory();
$garanify = new Garanify\Garanify(getenv('GARANIFY_SECRET_KEY'), ['httpClient' => new GuzzleHttp\Client(), 'requestFactory' => $factory, 'streamFactory' => $factory]);
$delivery = $garanify->webhooks->test();
import os, requests

res = requests.post(
    "https://api.garanify.com/v1/shops/shp_4kq8Zt2mWc9x/webhook/test",
    headers={"Authorization": f"Bearer {os.environ['GARANIFY_SECRET_KEY']}"},
    timeout=10,
)
res.raise_for_status()
data = res.json()