Treceți la conținut
Garanify

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 https on a public host name. IP addresses, localhost, .local, .internal and 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.

Delivery
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

  1. Read the raw body before any framework parses it as JSON.
  2. Read t and every v1 from the header. Reject if t is more than 300 seconds away from now (replay protection).
  3. Compute HMAC-SHA256 and compare in constant time.
  4. Answer with 2xx within 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" -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); // 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) or pending. We do not expose the exact HTTP status of your endpoint.
  • lastDelivery on 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 createdAt or 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()