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
httpsauf einem öffentlichen Hostnamen. IP-Adressen,localhost,.local,.internalund 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.
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
- Den rohen Body lesen, bevor ein Framework ihn als JSON parst.
tund allev1aus dem Header lesen. Liegttmehr als 300 Sekunden von jetzt entfernt, ablehnen (Schutz vor Wiedereinspielen).- HMAC-SHA256 berechnen und in konstanter Zeit vergleichen.
- Mit
2xxantworten, 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" -heximport { 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) oderpending. Den genauen HTTP-Status Ihres Endpunkts zeigen wir nicht. lastDeliveryam 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
createdAtoder 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()