Webhooks
Garanify tells your server when a product cannot show a valid label or the plan changes. Every delivery is signed, stored and can be sent again.
The API is built and tested. Hosting at api.garanify.com is in preparation; until then it runs locally. Keys are available on request.
Set up an endpoint
A shop has one webhook endpoint. PUT …/webhook sets the URL and the subscribed events and returns the signing secret whsec_… the first time, only that once. Send rotateSecret: true to get a new one.
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()- Only
httpson a public host name. IP addresses,localhost,.local,.internaland credentials in the URL are rejected (webhook_url_invalid). - If the host name resolves to a non-public address at delivery time, we do not deliver (outcome
unreachable). We do not follow redirects.
Events
Every event has id, type, createdAt, shop, livemode and data. GET /v1/webhook-events returns the same list with examples. New event types may be added; ignore unknown ones.
product.invalid
A product has guarantee data that cannot be shown
{
"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
The plan or licence state of the shop changed
{
"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.teston request only
Test event, sent only with POST /v1/shops/{shop}/webhook/test
{
"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."
}
} Signature
Every delivery carries the header Garanify-Signature: t=<unix seconds>,v1=<hex>. v1 is HMAC-SHA256 over <t>.<raw body>, keyed with the secret whsec_… as UTF-8. Garanify-Webhook-Id carries the event 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":{…}} Verify the signature
- Read the raw body before any framework parses it as JSON.
- Read
tand everyv1from the header. Reject iftis more than 300 seconds away from now (replay protection). - Compute HMAC-SHA256 and compare in constant time.
- Answer with
2xxwithin 5 seconds. Put slow work in a queue.
# Recompute a signature by hand (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); // raw body, do not JSON.parse first
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'); // raw 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", ""))A complete receiver is in examples/node-webhook, the PHP version in examples/php/webhook.php.
Delivery and retries
- Up to three attempts: at once, after 10 seconds and after another 60 seconds. Each attempt waits at most 5 seconds.
- Outcome per delivery:
delivered(2xx),rejected(another status),unreachable(no connection, timeout, non-public address) orpending. We do not expose the exact HTTP status of your endpoint. lastDeliveryon the endpoint (GET …/webhook) shows{ at, ok, outcome }of the last delivery.- Events can arrive more than once, for example after a redelivery. Dedupe by
id. - Order is not guaranteed. Use
createdAtor read the current state from the API.
Inspect and redeliver
We keep deliveries for 30 days. List them with a cursor, newest first; redeliver sends the same body with the same event ID to the current URL, signed with the current 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()Testing
POST …/webhook/test sends a signed webhook.test event even if you did not subscribe to it. For local tests without a public URL, signWebhook() (Node.js) and Webhook::sign() (PHP) build valid headers.
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()