Zum Inhalt springen
Garanify

Webhooks

Signierte Benachrichtigungen über ungültige Produkte und Lizenzänderungen.

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.

Feldbeschreibungen auf Englisch, direkt aus der OpenAPI-Datei.

Webhook-Endpunkt abrufen

GET /v1/shops/{shop}/webhook

Schlüssel: Secret Key

Parameter

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

Anfrage

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

Antworten

  • 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

Webhook-Endpunkt setzen

PUT /v1/shops/{shop}/webhook

Schlüssel: Secret Key

Ein HTTPS-Endpunkt je Shop. Das Signaturgeheimnis kommt beim Anlegen oder mit rotateSecret zurück.

Parameter

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

Body

NameTypBeschreibung
urlPflicht string ≤ 500 chars
eventsPflicht "product.invalid" | "license.changed"[] 1–∞ items
rotateSecret boolean

Anfrage

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

Antwort 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"
}

Antworten

  • 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

Webhook-Endpunkt löschen

DELETE /v1/shops/{shop}/webhook

Schlüssel: Secret Key

Parameter

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

Anfrage

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

Antworten

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

Test-Ereignis senden

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

Schlüssel: Secret Key

Sendet ein signiertes webhook.test-Ereignis an den Endpunkt, auch wenn er andere Ereignisse abonniert hat. Damit prüfen Sie Ihre Signaturprüfung. Die Zustellung läuft im Hintergrund; das Ergebnis steht in den Zustellungen.

Parameter

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

Anfrage

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

Antwort 202 application/json

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

Antworten

  • 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

Zustellungen auflisten

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

Schlüssel: Secret Key

Zustellungen der letzten 30 Tage, neueste zuerst. Ergebnis delivered (2xx), rejected (anderer Status), unreachable oder pending; den genauen HTTP-Status Ihres Endpunkts zeigen wir nicht.

Parameter

NameOrtTypBeschreibung
shopPflicht 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

Anfrage

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

Antwort 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
}

Antworten

  • 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

Zustellung erneut senden

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

Schlüssel: Secret Key

Sendet das gespeicherte Ereignis noch einmal, mit gleichem Body und gleicher Ereignis-ID, an die aktuelle URL und mit dem aktuellen Secret signiert. Entdoppeln Sie auf Ihrer Seite über die Ereignis-ID.

Parameter

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

Anfrage

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

Antworten

  • 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

Ereignistypen auflisten

GET /v1/webhook-events

Schlüssel: keiner

Jeder Ereignistyp mit Beschreibung und Beispiel. subscribable = false heißt: nur auf Anfrage (webhook.test).

Anfrage

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

Antworten

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

Weiter: Meta