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
| Name | In | Type | Description |
|---|---|---|---|
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()Try it GET /v1/shops/{shop}/webhook
Responses
200The endpoint. ·WebhookEndpoint401Key missing, invalid, expired or revoked. ·Problem404Not found. ·Problem429Too 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
| Name | In | Type | Description |
|---|---|---|---|
shoprequired | path | string | Shop ID (shp_…).pattern ^shp_[A-Za-z0-9]{12}$ |
Body
| Name | Type | Description |
|---|---|---|
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()Try it PUT /v1/shops/{shop}/webhook
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
200The endpoint. `secret` only on creation or rotation. ·WebhookEndpoint401Key missing, invalid, expired or revoked. ·Problem422The request does not match the schema. ·Problem429Too many requests. Wait `Retry-After` seconds. ·Problem
Delete the webhook endpoint
DELETE /v1/shops/{shop}/webhook
Key: Secret key
Parameters
| Name | In | Type | Description |
|---|---|---|---|
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()Try it DELETE /v1/shops/{shop}/webhook
Responses
204Deleted.401Key missing, invalid, expired or revoked. ·Problem429Too 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
| Name | In | Type | Description |
|---|---|---|---|
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()Try it POST /v1/shops/{shop}/webhook/test
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
202Delivery queued. ·WebhookDelivery401Key missing, invalid, expired or revoked. ·Problem404Not found. ·Problem429Too 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
| Name | In | Type | Description |
|---|---|---|---|
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()Try it GET /v1/shops/{shop}/webhook/deliveries
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
200One page of deliveries. ·WebhookDeliveryList401Key missing, invalid, expired or revoked. ·Problem422The request does not match the schema. ·Problem429Too 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
| Name | In | Type | Description |
|---|---|---|---|
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()Try it POST /v1/shops/{shop}/webhook/deliveries/{delivery}/retry
Responses
202Delivery queued. ·WebhookDelivery401Key missing, invalid, expired or revoked. ·Problem404Not found. ·Problem422The request does not match the schema. ·Problem429Too 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()Try it GET /v1/webhook-events
Responses
200The event catalogue. ·WebhookEventTypeList429Too many requests. Wait `Retry-After` seconds. ·Problem