Pereiti prie turinio
Garanify

Webhooks

Signed notifications about invalid products and licence changes.

The API is built and tested. Hosting at api.garanify.com is in preparation; until then it runs locally. Keys are available on request.

Retrieve the webhook endpoint

GET /v1/shops/{shop}/webhook

Key: Secret key

Parameters

NameInTypeDescription
shoprequired path string Shop ID (shp_…).pattern ^shp_[A-Za-z0-9]{12}$

Request

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

const garanify = new Garanify({ apiKey: process.env.GARANIFY_SECRET_KEY });
const endpoint = await garanify.webhooks.retrieve();
<?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->retrieve();
import os, requests

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

Responses

  • 200 The endpoint. · WebhookEndpoint
  • 401 Key missing, invalid, expired or revoked. · Problem
  • 404 Not found. · Problem
  • 429 Too many requests. Wait `Retry-After` seconds. · Problem

Set the webhook endpoint

PUT /v1/shops/{shop}/webhook

Key: Secret key

One HTTPS endpoint per shop on a public host name. Deliveries connect only to public unicast addresses (checked on every connection, also for IPv6) and do not follow redirects. The signing secret is returned when the endpoint is created or when you send rotateSecret.

Parameters

NameInTypeDescription
shoprequired path string Shop ID (shp_…).pattern ^shp_[A-Za-z0-9]{12}$

Body

NameTypeDescription
urlrequired string ≤ 500 chars
eventsrequired "product.invalid" | "license.changed"[] 1–∞ items
rotateSecret boolean

Request

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()

Response 200 application/json

{
  "url": "https://mein-shop.example/hooks/garanify",
  "events": [
    "product.invalid",
    "license.changed"
  ],
  "createdAt": "2026-11-18T10:00:00Z",
  "lastDelivery": null,
  "secret": "whsec_EXAMPLEONLY"
}

Responses

  • 200 The endpoint. `secret` only on creation or rotation. · WebhookEndpoint
  • 401 Key missing, invalid, expired or revoked. · Problem
  • 422 The request does not match the schema. · Problem
  • 429 Too many requests. Wait `Retry-After` seconds. · Problem

Delete the webhook endpoint

DELETE /v1/shops/{shop}/webhook

Key: Secret key

Parameters

NameInTypeDescription
shoprequired path string Shop ID (shp_…).pattern ^shp_[A-Za-z0-9]{12}$

Request

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

const garanify = new Garanify({ apiKey: process.env.GARANIFY_SECRET_KEY });
await garanify.webhooks.delete();
<?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]);
$garanify->webhooks->delete();
import os, requests

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

Responses

  • 204 Deleted.
  • 401 Key missing, invalid, expired or revoked. · Problem
  • 429 Too many requests. Wait `Retry-After` seconds. · Problem

Send a test event

POST /v1/shops/{shop}/webhook/test

Key: Secret key

Sends a signed webhook.test event to the endpoint, whether or not it subscribes to other events. Use it to check your signature verification. The delivery runs in the background; read its outcome from the deliveries.

Parameters

NameInTypeDescription
shoprequired path string Shop ID (shp_…).pattern ^shp_[A-Za-z0-9]{12}$

Request

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()

Response 202 application/json

{
  "id": "whd_6Tq2Lm9Xc4Vb",
  "eventId": "evt_2Wd8Kp4Rt6Yn",
  "type": "webhook.test",
  "createdAt": "2026-11-18T10:00:00Z",
  "attempts": 0,
  "lastAttemptAt": null,
  "outcome": "pending"
}

Responses

  • 202 Delivery queued. · WebhookDelivery
  • 401 Key missing, invalid, expired or revoked. · Problem
  • 404 Not found. · Problem
  • 429 Too many requests. Wait `Retry-After` seconds. · Problem

List webhook deliveries

GET /v1/shops/{shop}/webhook/deliveries

Key: Secret key

Deliveries of the last 30 days, newest first. The outcome is delivered (2xx), rejected (another status), unreachable or pending; the exact HTTP status of your endpoint is not exposed.

Parameters

NameInTypeDescription
shoprequired path string Shop ID (shp_…).pattern ^shp_[A-Za-z0-9]{12}$
limit query integer Page size.≥ 1, ≤ 100, default 20
cursor query string Value of nextCursor from the previous page.≤ 100 chars

Request

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()

Response 200 application/json

{
  "data": [
    {
      "id": "whd_6Tq2Lm9Xc4Vb",
      "eventId": "evt_3Hk9Lm2Pq7Rs",
      "type": "product.invalid",
      "createdAt": "2026-11-18T10:00:00Z",
      "attempts": 1,
      "lastAttemptAt": "2026-11-18T10:00:01Z",
      "outcome": "delivered"
    }
  ],
  "nextCursor": null
}

Responses

  • 200 One page of deliveries. · WebhookDeliveryList
  • 401 Key missing, invalid, expired or revoked. · Problem
  • 422 The request does not match the schema. · Problem
  • 429 Too many requests. Wait `Retry-After` seconds. · Problem

Send a delivery again

POST /v1/shops/{shop}/webhook/deliveries/{delivery}/retry

Key: Secret key

Sends the stored event again with the same body and event ID, to the current URL and signed with the current secret. Deduplicate by event ID on your side.

Parameters

NameInTypeDescription
shoprequired path string Shop ID (shp_…).pattern ^shp_[A-Za-z0-9]{12}$
deliveryrequired path string Delivery ID (whd_…).pattern ^whd_[A-Za-z0-9]{12}$

Request

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()

Responses

  • 202 Delivery queued. · WebhookDelivery
  • 401 Key missing, invalid, expired or revoked. · Problem
  • 404 Not found. · Problem
  • 422 The request does not match the schema. · Problem
  • 429 Too many requests. Wait `Retry-After` seconds. · Problem

List event types

GET /v1/webhook-events

Key: none

Every event type with a description and an example payload. subscribable = false marks events that are sent on request only (webhook.test).

Request

curl "https://api.garanify.com/v1/webhook-events"
import { Garanify } from '@garanify/sdk';

const garanify = new Garanify({ apiKey: process.env.GARANIFY_SECRET_KEY });
const events = await garanify.meta.webhookEvents();
<?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]);
$events = $garanify->meta->webhookEvents();
import os, requests

res = requests.get(
    "https://api.garanify.com/v1/webhook-events",
    timeout=10,
)
res.raise_for_status()
data = res.json()

Responses

  • 200 The event catalogue. · WebhookEventTypeList
  • 429 Too many requests. Wait `Retry-After` seconds. · Problem

Next: Meta