Webhooks

Webhooks ermöglichen es Ihnen, Echtzeit-Benachrichtigungen über Ereignisse in Ihrem ZepDesk-Account zu erhalten. Wenn ein bestimmtes Ereignis eintritt (z. B. eine neue Rechnung wird erstellt), sendet ZepDesk eine HTTP-POST-Anfrage an die von Ihnen hinterlegte URL.

Voraussetzung

Die Webhook-Funktion ist abhängig von Ihrem Plan. Prüfen Sie unter Mein Konto → Abo, ob Webhooks in Ihrem Plan enthalten sind.

Webhook erstellen

1. Navigieren Sie zu Mein Konto → Webhooks.
2. Klicken Sie auf Webhook erstellen.
3. Geben Sie eine Bezeichnung ein (z. B. „Buchhaltungsintegration").
4. Geben Sie die Ziel-URL ein (muss https:// verwenden).
5. Wählen Sie die Events aus, die Sie abonnieren möchten.
6. Klicken Sie auf Erstellen.

Nach der Erstellung erhalten Sie ein Signing Secret (HMAC-Schlüssel). Dieses wird nur einmal angezeigt.

Achtung

Speichern Sie das Signing Secret sofort und sicher. Es wird nicht erneut angezeigt und ist erforderlich, um die Echtheit eingehender Webhooks zu verifizieren.

Verfügbare Events

Payload-Format

Jeder Webhook wird als HTTP-POST mit JSON-Body gesendet:

{
  "event": "invoice.created",
  "timestamp": "2026-04-16T10:30:00Z",
  "data": {
    "id": "CR-2026-0042",
    "betrag": 49.00,
    "status": "Offen",
    "rechnungsdatum": "2026-04-16"
  }
}

Signatur verifizieren

Jede Webhook-Anfrage enthält einen X-ZepDesk-Signature-Header mit einer HMAC-SHA256-Signatur. Verifizieren Sie diese, um sicherzustellen, dass die Anfrage tatsächlich von ZepDesk stammt.

Python

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode("utf-8"),
        payload,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Node.js

const crypto = require("crypto");

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(`sha256=${expected}`),
    Buffer.from(signature)
  );
}

Wiederholungsversuche (Retry)

Wenn Ihre Ziel-URL nicht mit einem HTTP-Statuscode 2xx antwortet, wird der Webhook erneut gesendet:

Nach 5 fehlgeschlagenen Versuchen wird der Webhook als fehlgeschlagen markiert und nicht erneut gesendet.

Webhook testen

1. Navigieren Sie zu Mein Konto → Webhooks.
2. Klicken Sie auf den gewünschten Webhook.
3. Klicken Sie auf Test-Event senden.

Es wird ein webhook.test-Event an Ihre Ziel-URL gesendet.

Webhook löschen

1. Navigieren Sie zu Mein Konto → Webhooks.
2. Klicken Sie auf den gewünschten Webhook.
3. Klicken Sie auf Löschen und bestätigen Sie die Aktion.