Webhooks

Ein Webhook meldet ein Ereignis in ZepDesk, etwa eine bezahlte Rechnung, als HTTP-POST an eine Adresse Ihrer Wahl: an ein Szenario in Make, einen Zap in Zapier oder ein eigenes System. Ein Webhook gehört zu der Firma, in der Sie ihn anlegen, und bekommt nur Ereignisse dieser Firma.

Webhook anlegen

Webhooks legt die Rolle Verwaltung selbst an, unter Hilfe & Glossar, Schnittstelle, Ansicht Webhooks. Nur-Lesen sieht die Liste, von der Zieladresse aber nur den Rechner, denn wer die volle Empfangsadresse kennt, kann dort selbst Nachrichten einwerfen.

Angabe	Bedeutung
Name	Kennung des Webhooks, etwa „Make Rechnungen“. Er lässt sich später nicht ändern.
Zieladresse	Nur https, nur ein öffentlich erreichbarer Rechner.
Ereignisse	Eines oder mehrere aus der Liste unten.
Beschreibung	Wofür der Webhook da ist.
Aktiv	Ob er sofort meldet. Vorgabe: ja.
Zeitlimit	1 bis 15 Sekunden je Zustellung. Vorgabe: 10.
Wiederholungen	0 bis 5 nach einem Fehlschlag. Vorgabe: 5.

Beim Anlegen zeigt ZepDesk das Signaturgeheimnis genau einmal. Hinterlegen Sie es in Ihrem Empfänger; danach liegt es bei uns nur noch verschlüsselt. Neues Signaturgeheimnis erzeugt ein neues, das alte gilt ab der nächsten Zustellung nicht mehr. Über die Schnittstelle können Sie dabei auch ein eigenes Geheimnis mit 32 bis 256 druckbaren Zeichen vorgeben.

Eine Zieladresse im eigenen Netz lehnt ZepDesk ab, auch wenn erst die Namensauflösung dorthin führt. Weiterleitungen folgt ZepDesk nicht; tragen Sie die endgültige Adresse ein.

Anlegen, Ändern, Löschen und neue Geheimnisse sind auf 30 je Benutzer und Minute begrenzt, Proben auf 10. Darüber antwortet ZepDesk mit HTTP 429.

Ereignisse

Jede Nutzlast trägt doctype und name des Datensatzes, dazu die Felder des Ereignisses:

• rechnung.erstellt (Rechnung erstellt): kunde, kundenname, status
• rechnung.versendet (Rechnung versendet): kunde, kundenname, status, vorheriger_status
• rechnung.bezahlt (Rechnung bezahlt): kunde, kundenname, status, vorheriger_status
• rechnung.ueberfaellig (Rechnung überfällig): kunde, kundenname, status, vorheriger_status
• beleg.erfasst (Beleg erfasst): status, titel
• beleg.gebucht (Beleg gebucht): status, vorheriger_status, titel, lieferant, betrag
• mahnung.versendet (Mahnung versendet): kunde, mahnstufe, gesamtbetrag, status
• zahlung.eingegangen (Zahlung eingegangen): rechnung, kunde, kundenname, betrag, offen, status
• kunde.angelegt (Kunde angelegt): kundenname, status
• kunde.geaendert (Kunde geändert): kundenname, status, geaenderte_felder
• angebot.angenommen (Angebot angenommen): kunde, kundenname, angebotsnummer, brutto_summe, status

Dieselbe Liste liefert die REST-API unter GET /webhook-events, mit einem Schlüssel der Rolle Verwaltung.

Eine Zustellung

ZepDesk schickt einen POST mit JSON, gleich nachdem das Ereignis eingetreten ist:

• Content-Type: application/json; charset=utf-8
• User-Agent: ZepDesk-Webhook/2.0
• X-ZepDesk-Event: Name des Ereignisses, etwa rechnung.bezahlt
• X-ZepDesk-Attempt: Nummer des Versuchs, ab 1
• X-ZepDesk-Delivery: Kennung der Zustellung, bei jeder Wiederholung dieselbe
• X-ZepDesk-Timestamp: Zeitpunkt des Versands in Unix-Sekunden
• X-ZepDesk-Signature: sha256= und die Signatur, siehe unten
• X-ZepDesk-Test: 1, nur bei einer Probe

Der Körper, etwa bei rechnung.bezahlt:

{
  "doctype": "Rechnung",
  "kunde": "KD-00123",
  "kundenname": "Muster GmbH",
  "name": "RE-2026-0042",
  "status": "Bezahlt",
  "vorheriger_status": "Festgeschrieben"
}

Die Schlüssel stehen in alphabetischer Reihenfolge. doctype heißt bei Belegen Beleg, bei Mahnungen Mahnung und bei Zahlungen auf offene Posten Offener Posten.

Signatur prüfen

Die Signatur ist HMAC-SHA256 mit dem Signaturgeheimnis über den Zeitstempel aus X-ZepDesk-Timestamp, einen Punkt und den unveränderten Körper. Vergleichen Sie in konstanter Zeit und verwerfen Sie Nachrichten, deren Zeitstempel älter als fünf Minuten ist. An X-ZepDesk-Delivery erkennen Sie eine Zustellung, die Sie schon verarbeitet haben.

import hashlib
import hmac
import time

def verify_webhook(body: bytes, timestamp: str, signature: str, secret: str) -> bool:
    if abs(time.time() - int(timestamp)) > 300:
        return False
    signed = timestamp.encode("ascii") + b"." + body
    expected = hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Wiederholungen

Zugestellt ist eine Nachricht, wenn Ihre Adresse mit einem Status 2xx antwortet. Eine Weiterleitung 3xx, ein anderer Status, keine Antwort oder das Zeitlimit gelten als Fehlschlag. Dann versucht ZepDesk es so oft erneut, wie unter Wiederholungen eingestellt ist, frühestens nach 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden und 12 Stunden. Fällige Wiederholungen sammelt ZepDesk alle fünf Minuten ein.

Zwei Fälle wiederholt ZepDesk nicht:

• Abgelehnte Zieladresse. Zeigt die Adresse nicht auf einen öffentlichen Rechner, geht nichts hinaus.
• HTTP 410. Damit sagt der Empfänger, dass es das Abonnement nicht mehr gibt; Zapier antwortet so, wenn ein Zap ausgeschaltet ist. ZepDesk schaltet den Webhook ab und vermerkt den Grund. Prüfen Sie den Empfänger und schalten Sie den Webhook danach wieder ein.

Probe

Probe senden stellt sofort genau eine Nachricht zu, ohne Wiederholung, auch an einen abgeschalteten Webhook. Sie trägt die Felder des ersten abonnierten Ereignisses mit Beispielwerten; über die Schnittstelle (POST /webhooks/{id}/test) wählen Sie das Ereignis selbst. doctype und status lauten Probe, und der Kopf X-ZepDesk-Test: 1 kennzeichnet sie. Make und Zapier bauen aus einer Probe die Zuordnung der Felder.

Zustellprotokoll

Je Webhook zeigt ZepDesk die letzten 50 Zustellungen und Proben mit Zeitpunkt, Ereignis, Versuch, Status, Dauer und Fehler. Die Nutzlast steht dort nicht; verschlüsselt aufbewahrt wird sie nur, solange eine Wiederholung sie noch braucht.

Make und Zapier anbinden

Eine eigene ZepDesk-App in den Verzeichnissen von Make oder Zapier gibt es nicht. Beide binden Sie mit ihren allgemeinen Bausteinen an: Auslöser über einen Webhook von ZepDesk, Aktionen über die REST-API mit einem API-Schlüssel. Die Karten Make und Zapier unter Verwaltung, Firma, Integrationen führen auf die Ansicht Webhooks und zeigen dort dieselben Schritte:

1. Unter Hilfe & Glossar, Schnittstelle, Ansicht Zugang, einen API-Schlüssel erzeugen und in Make oder Zapier als Verbindung hinterlegen, mit dem Kopf Authorization: token Schlüssel:Geheimnis. Der Schlüssel hat die Rechte der Verwaltung dieser Firma.
2. In Make ein Szenario mit dem Auslöser „Custom webhook“ anlegen, in Zapier einen Zap mit „Webhooks by Zapier“ und „Catch Hook“, und die Empfangsadresse kopieren.
3. In ZepDesk einen Webhook mit dieser Adresse anlegen und die Ereignisse wählen.
4. Probe senden: Make oder Zapier bekommt Beispieldaten und kann die Felder zuordnen.

Als verbunden steht eine Karte da, sobald ein aktiver Webhook dieser Firma auf eine Adresse bei make.com oder integromat.com (Make) beziehungsweise zapier.com (Zapier) zeigt; ist dessen letzte Zustellung gescheitert, steht sie als gestört da. Eine Anbindung, die nur Aktionen über den API-Schlüssel ausführt, erkennt ZepDesk nicht; die Karte zeigt dann „nicht verbunden“, obwohl die Aktionen laufen.