Webhooks-Leitfaden

1. Erstellen Sie einen Webhook-Endpunkt

Erstellen Sie zunächst einen HTTP-Endpunkt in Ihrer Anwendung, der POST-Anfragen von LicenseChain empfangen kann.

// Express.js Example
app.post('/webhooks/licensechain', async (req, res) => {'{'}
  const signature = req.headers['x-webhook-signature'];
  const timestamp = req.headers['x-webhook-timestamp'];
  const payload = JSON.stringify(req.body);
  
  // Verify signature (see Security section)
  if (!verifySignature(payload, signature, timestamp, webhookSecret)) {'{'}
    return res.status(401).send('Invalid signature');
  {'}'}
  
  // Process webhook event
  const event = req.body;
  console.log('Received event:', event.type, event.data);
  
  res.status(200).send('OK');
{'}'});

2. Registrieren Sie Ihren Webhook

Verwenden Sie die LicenseChain-API, um Ihren Webhook-Endpunkt zu registrieren. Sie müssen die URL angeben und angeben, welche Ereignisse Sie erhalten möchten.

POST /v1/webhooks
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{'{'}
  "url": "https://your-app.com/webhooks/licensechain",
  "events": ["license.created", "license.updated", "license.revoked"],
  "secret": "optional-custom-secret"
{'}'}

3. Verfügbare Veranstaltungen

LicenseChain unterstützt die folgenden Webhook-Ereignisse:

Webhook-Signaturen

Alle Webhook-Anfragen enthalten eine Signatur im X-Webhook-Signature Kopfzeile. Die Signatur des rohen Anforderungstexts lautet HMAC-SHA256 und verwendet Ihr Webhook-Geheimnis. Überprüfen Sie immer die Verwendung Konstantzeitvergleich (z.B. crypto.timingSafeEqual), um Timing-Angriffe zu verhindern. Der Header-Wert kann unformatiert hexadezimal oder sein sha256= gefolgt von Hex; Streifen Sie die sha256= Präfix vor dem Vergleich von Hex-Puffer, damit die Längen übereinstimmen.

// Node.js Example (constant-time, supports sha256= prefix)
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {'{'}
  if (!payload || !signature || !secret) return false;
  const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
  const received = String(signature).startsWith('sha256=') ? String(signature).slice(7) : String(signature);
  const a = Buffer.from(expected, 'hex');
  const b = Buffer.from(received, 'hex');
  if (a.length !== b.length) return false;
  return crypto.timingSafeEqual(a, b);
{'}'}

// In your webhook handler (use raw body for payload)
const signature = req.headers['x-webhook-signature'];
const payload = req.rawBody || JSON.stringify(req.body);
if (!verifySignature(payload, signature, webhookSecret)) {'{'}
  return res.status(401).send('Invalid signature');
{'}'}

Header anfordern

LicenseChain enthält bei jeder Webhook-Anfrage die folgenden Header:

Alle Webhooks auflisten

GET /v1/webhooks?page=1&limit=10
Authorization: Bearer YOUR_API_KEY

Webhook-Details abrufen

GET /v1/webhooks/:id
Authorization: Bearer YOUR_API_KEY

Webhook aktualisieren

PUT /v1/webhooks/:id
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{'{'}
  "url": "https://new-url.com/webhooks",
  "events": ["license.created", "license.updated"]
{'}'}

Webhook löschen

DELETE /v1/webhooks/:id
Authorization: Bearer YOUR_API_KEY

Test-Webhook senden

Sie können Ihren Webhook-Endpunkt testen, ohne auf das Eintreten eines echten Ereignisses warten zu müssen:

POST /v1/webhooks/:id/test
Authorization: Bearer YOUR_API_KEY

Dadurch wird ein Testereignis mit einer Beispielnutzlast an Ihre Webhook-URL gesendet. Verwenden Sie dies, um zu überprüfen, ob Ihr Endpunkt ordnungsgemäß funktioniert.

Webhook-Protokolle anzeigen

Überprüfen Sie den Zustellungsstatus und die Antwort für jedes Webhook-Ereignis:

GET /v1/webhooks/:id/logs?page=1&limit=10
Authorization: Bearer YOUR_API_KEY

Zu den Protokollen gehören der HTTP-Statuscode, der Antworttext und ob die Zustellung erfolgreich war.

✅ Überprüfen Sie immer die Unterschriften

Verarbeiten Sie niemals Webhook-Ereignisse, ohne die Signatur zu überprüfen. Dadurch wird sichergestellt, dass die Anfrage von LicenseChain stammt und nicht manipuliert wurde.

✅ Reagieren Sie schnell

Ihr Webhook-Endpunkt sollte innerhalb von 5 Sekunden antworten. Bestätigen Sie bei Vorgängen mit langer Laufzeit den Webhook sofort und verarbeiten Sie ihn asynchron.

✅ Umgang mit Idempotenz

Verwenden Sie die Ereignis-ID, um zu verhindern, dass dasselbe Ereignis mehrmals verarbeitet wird. Speichern Sie verarbeitete Ereignis-IDs und überprüfen Sie sie vor der Verarbeitung.

✅ Verwenden Sie HTTPS

Verwenden Sie für Ihre Webhook-Endpunkte immer HTTPS, um sicherzustellen, dass die Daten während der Übertragung verschlüsselt werden.

✅ Überwachen Sie Webhook-Protokolle

Überprüfen Sie regelmäßig die Webhook-Protokolle, um Zustellungsprobleme zu erkennen und zu beheben. Richten Sie Benachrichtigungen für fehlgeschlagene Lieferungen ein.

Webhook empfängt keine Ereignisse

• • Stellen Sie sicher, dass Ihre Webhook-URL über das Internet zugänglich ist
• • Überprüfen Sie, ob Ihr Endpunkt einen 2xx-Statuscode zurückgibt
• • Stellen Sie sicher, dass die Ereignisse, die Sie abonniert haben, tatsächlich stattfinden
• • Überprüfen Sie die Webhook-Protokolle auf Zustellungsfehler

Signaturüberprüfung schlägt fehl

• • Stellen Sie sicher, dass Sie das richtige Webhook-Geheimnis verwenden
• • Stellen Sie sicher, dass Sie den genauen Anforderungstext signieren (als JSON-Zeichenfolge).
• • Überprüfen Sie, ob Sie den HMAC-SHA256-Algorithmus verwenden
• • Stellen Sie sicher, dass die Header korrekt gelesen werden (Groß- und Kleinschreibung beachten).

Timeout-Fehler

• • Optimieren Sie Ihren Webhook-Handler, um schnell zu reagieren
• • Verlagern Sie schwere Verarbeitungsvorgänge in Hintergrundjobs
• • 200 OK sofort zurückgeben und asynchron verarbeiten