Webhooks

Pro Plan

Konfigurieren Sie ausgehende Webhooks, um in Echtzeit Benachrichtigungen von Zenovay zu erhalten, sobald Plattformereignisse auftreten, und erfahren Sie, wie Zenovay eingehende Zahlungs-Webhooks intern verarbeitet.

Ausgehende Webhooks

Zenovay unterstützt benutzerkonfigurierbare ausgehende Webhooks, sodass Ihre Dienste auf Plattformereignisse reagieren können, sobald sie eintreten, anstatt die API auf Änderungen abzufragen.

Plan-Verfügbarkeit

Das Verwalten ausgehender Webhooks über die API erfordert einen persönlichen API-Token, und API-Token sind ein kostenpflichtiges Feature. Sie sind auf Pro und höher verfügbar (Free-Pläne können keine API-Token erstellen). Erstellen Sie einen Token unter Settings → Account → Security & access (app.zenovay.com/settings/account/security). Webhooks sind auf das Team bezogen, dem dieser Token angehört.

Einen Webhook erstellen

Webhooks werden unter /v1/cli/mutate/webhooks in der Zenovay API verwaltet. Geben Sie die Ziel-url (muss https:// sein) und mindestens einen Ereignistyp an. Erstellen Sie einen mit einer POST-Anfrage:

curl -X POST https://api.zenovay.com/v1/cli/mutate/webhooks \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://yoursite.com/zenovay-hook","events":["traffic_spike"]}'

Die Antwort enthält die Webhook-id und ein Signatur-secret. Das secret wird nur bei der Erstellung zurückgegeben — speichern Sie es sofort an einem sicheren Ort. Wenn Sie es verlieren, rotieren Sie das secret (siehe unten); das ursprüngliche kann nicht wiederhergestellt werden.

Webhooks auflisten

curl https://api.zenovay.com/v1/cli/mutate/webhooks \
  -H "Authorization: Bearer YOUR_TOKEN"

Webhook-Signaturen verifizieren

Jede Webhook-Zustellung wird mit dem bei der Erstellung erhaltenen Signatur-secret HMAC-signiert. Verifizieren Sie die Signatur an Ihrem Endpunkt, bevor Sie der Payload vertrauen, und verwenden Sie einen zeitkonstanten Vergleich, damit die Verifizierung nicht anfällig für Timing-Angriffe ist:

import crypto from 'crypto';

function verifyZenovayWebhook(rawBody, signatureHeader, secret) {
  // The signature header value is prefixed with the algorithm,
  // e.g. "sha256=<hex>". Strip the prefix before comparing.
  const received = (signatureHeader || '').replace(/^sha256=/, '');

  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  // timingSafeEqual throws if the buffers differ in length, so
  // length-check first, then compare in constant time.
  if (expected.length !== received.length) return false;
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(received)
  );
}

Validieren Sie immer den Roh-Anfragetext (die exakten empfangenen Bytes), nicht eine neu serialisierte Version, damit die von Ihnen berechnete Signatur mit der von Zenovay berechneten übereinstimmt.

Der genaue Header-Name, der die Signatur enthält, ist in der REST API-Referenz dokumentiert.

Einen Webhook testen

Senden Sie eine synthetische Test-Zustellung, um zu bestätigen, dass Ihr Endpunkt korrekt eingerichtet ist. Die Antwort enthält das Ergebnis des Zustellversuchs (HTTP-Status Ihres Endpunkts und Dauer):

curl -X POST https://api.zenovay.com/v1/cli/mutate/webhooks/{id}/test \
  -H "Authorization: Bearer YOUR_TOKEN"

Das Signatur-secret rotieren

Wenn ein secret durchsickert oder Sie es regelmäßig rotieren möchten, rotieren Sie es. Das neue secret wird in der Antwort nur einmal zurückgegeben:

curl -X POST https://api.zenovay.com/v1/cli/mutate/webhooks/{id}/rotate \
  -H "Authorization: Bearer YOUR_TOKEN"

Aktualisieren Sie nach der Rotation Ihren Endpunkt, damit er mit dem neuen secret verifiziert. Alte Signaturen werden sofort ungültig.

Einen Webhook widerrufen

curl -X DELETE https://api.zenovay.com/v1/cli/mutate/webhooks/{id} \
  -H "Authorization: Bearer YOUR_TOKEN"

Widerrufene Webhooks erhalten sofort keine Zustellungen mehr. Der Widerruf kann nicht rückgängig gemacht werden.

Best Practices

• Antworten Sie so schnell wie möglich mit einem 2xx. Bestätigen Sie zuerst, und verarbeiten Sie das Ereignis dann in einem Hintergrundjob.
• Seien Sie idempotent. Netzwerkwiederholungen können dazu führen, dass dasselbe Ereignis mehr als einmal eintrifft — basieren Sie Ihren Handler auf der Ereignis-id, nicht auf der Empfangszeit.
• Verifizieren, bevor Sie vertrauen. Lehnen Sie jede Anfrage ab, deren HMAC nicht validiert, und lehnen Sie Anfragen ab, deren Zeitstempel weit außerhalb eines akzeptablen Zeitfensters liegt.
• Rotieren Sie secrets, wenn jemand außerhalb des Teams Zugriff auf Ihre Webhook-Konfiguration oder -Logs hatte.

Eingehende Zahlungs-Webhooks

Zenovay verarbeitet außerdem eingehende Webhooks von externen Diensten zur Verwaltung von Abonnements und Infrastruktur. Diese laufen innerhalb der Zenovay-Plattform und erfordern keine Konfiguration durch Sie.

Quellen eingehender Webhooks

Quelle	Zweck
Stripe	Abonnementverwaltung, Zahlungsabwicklung, Checkout-Abschluss
Uptime-Monitoring	Health-Check-Trigger von externen Überwachungsdiensten

Polling-Alternativen

Wenn ausgehende Webhooks für Ihren Anwendungsfall nicht passen (zum Beispiel benötigen Sie zeitpunktbezogene Aggregate statt eines Ereignisstroms), können Sie Echtzeit-Integrationen weiterhin durch Polling der External API erstellen.

Die External API ist auch ein kostenpflichtiges Feature — es erfordert einen API-Schlüssel, und Free-Pläne haben keinen API-Zugriff. Die folgenden Endpunkte geben die Standard-{ success, data, timestamp }-Umhülung zurück, daher befindet sich Ihre Payload unter data.

Polling mit der External API

const API_KEY = process.env.ZENOVAY_API_KEY;
const WEBSITE_ID = process.env.ZENOVAY_WEBSITE_ID;

async function checkAnalytics() {
  const response = await fetch(
    `https://api.zenovay.com/api/external/v1/analytics/${WEBSITE_ID}?range=24h`,
    {
      headers: { 'X-API-Key': API_KEY }
    }
  );

  const { data } = await response.json();

  if (data.summary.total_visitors > threshold) {
    await sendSlackNotification(data);
  }
}

// Poll every 5 minutes
setInterval(checkAnalytics, 5 * 60 * 1000);

Der range-Parameter akzeptiert 24h, 7d, 30d, 90d oder 1y (Standard ist 7d).

Live-Besucherzählung

Verwenden Sie den öffentlichen Live-Endpunkt, um die aktuelle Besucherzahl ohne API-Schlüssel abzurufen:

async function getLiveVisitors(trackingCode) {
  const response = await fetch(
    `https://api.zenovay.com/e/live/${trackingCode}`
  );
  return await response.json();
}

Beispiel: Slack-Integration

Erstellen Sie einen geplanten Bericht, der an Slack gesendet wird:

async function sendDailyReport() {
  const response = await fetch(
    `https://api.zenovay.com/api/external/v1/analytics/${WEBSITE_ID}?range=24h`,
    {
      headers: { 'X-API-Key': API_KEY }
    }
  );

  const { data } = await response.json();
  const { summary } = data;

  await fetch(SLACK_WEBHOOK_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      text: `Daily Analytics Report:\n` +
            `Visitors: ${summary.total_visitors}\n` +
            `Unique Visitors: ${summary.unique_visitors}\n` +
            `Page Views: ${summary.total_page_views}`
    })
  });
}

Beispiel: CRM-Integration

Synchronisieren Sie Analysedaten planmäßig mit Ihrem CRM:

async function syncToCRM() {
  const response = await fetch(
    `https://api.zenovay.com/api/external/v1/analytics/${WEBSITE_ID}/visitors`,
    {
      headers: { 'X-API-Key': API_KEY }
    }
  );

  const { data } = await response.json();

  for (const visitor of data.visitors) {
    await crm.contacts.update({
      country: visitor.country_name,
      city: visitor.city,
      last_seen: visitor.visited_at
    });
  }
}

Rate Limits für Polling

Beachten Sie beim Erstellen von Polling-Integrationen die Rate Limits der External API:

Plan	Anfragen/Minute	Monatliches Limit
Free	10	1.000
Pro	30	10.000
Scale	60	100.000
Enterprise	120	1.000.000

Best Practices für Polling

• Speichern Sie API-Antworten lokal zwischen, um die Anfragehäufigkeit zu reduzieren
• Verwenden Sie angemessene Polling-Intervalle (mindestens 5 Minuten empfohlen)
• Überwachen Sie den X-RateLimit-Remaining-Header, um Limits nicht zu überschreiten
• Implementieren Sie exponentielles Backoff, wenn Sie 429-Antworten erhalten

Nächste Schritte

• API-Übersicht
• REST API-Referenz
• Rate Limits