Webhooks

Webhooks ermöglichen es Ihrer Anwendung, Echtzeit-Benachrichtigungen über Ereignisse in Milkee zu erhalten. Anstatt die API kontinuierlich abzufragen, sendet Milkee HTTP-POST-Anfragen an eine von Ihnen konfigurierte URL, wenn bestimmte Ereignisse auftreten.

Übersicht

Webhooks sind besonders nützlich für:

• Echtzeit-Synchronisation: Halten Sie externe Systeme synchron mit Milkee
• Automatisierung: Triggern Sie Workflows basierend auf Ereignissen
• Benachrichtigungen: Informieren Sie Benutzer über wichtige Änderungen
• Audit-Logging: Protokollieren Sie alle Änderungen in einem externen System

Webhook einrichten

Hinweis

Die Konfiguration von Webhooks erfolgt über die Milkee-Weboberfläche.

Anforderungen an den Webhook-Endpoint

Ihr Webhook-Endpoint sollte:

• HTTPS verwenden: Aus Sicherheitsgründen sollten Webhooks nur über HTTPS empfangen werden
• Schnell antworten: HTTP 200-299 Status innerhalb von 5 Sekunden zurückgeben
• Idempotent sein: Dieselbe Webhook-Nachricht kann mehrmals gesendet werden
• Validierung durchführen: Signatur-Header überprüfen (falls implementiert)

Webhook-Payload-Struktur

Alle Webhooks folgen einer einheitlichen Struktur:

{
  "event": "resource.action",
  "data": {
    // Ressourcen-spezifische Daten
  },
  "timestamp": 1705318200,
  "webhook_id": 123
}

Feld	Typ	Beschreibung
event	string	Ereignisname im Format resource.action
data	object	Die betroffene Ressource mit allen Attributen
timestamp	integer	Unix Timestamp des Ereignisses
webhook_id	integer	ID des Webhooks

Verfügbare Events

Webhooks sind für folgende Ressourcen verfügbar:

• Tags - Ereignisse für Tag-Erstellung, -Aktualisierung und -Löschung
• Customers - Ereignisse für Customer-Erstellung, -Aktualisierung und -Löschung
• Contacts - Ereignisse für Contact-Erstellung, -Aktualisierung und -Löschung
• Projects - Ereignisse für Project-Erstellung, -Aktualisierung und -Löschung
• Tasks - Ereignisse für Task-Erstellung, -Aktualisierung und -Löschung
• Time Tracking - Ereignisse für Time Track Entry-Erstellung, -Aktualisierung und -Löschung
• Entries - Ereignisse für Entry-Erstellung, -Aktualisierung und -Löschung
• Products - Ereignisse für Product-Erstellung, -Aktualisierung und -Löschung
• Accounts - Ereignisse für Account-Erstellung, -Aktualisierung und -Löschung
• Tax Rates - Ereignisse für Tax Rate-Erstellung, -Aktualisierung und -Löschung

Weitere Ressourcen werden in Zukunft hinzugefügt.

Best Practices

Schnelle Antwort

Ihr Webhook-Endpoint sollte innerhalb von 5 Sekunden mit einem HTTP-Status 200-299 antworten. Führen Sie die eigentliche Verarbeitung asynchron durch.

Idempotenz

Verwenden Sie die webhook_id, um sicherzustellen, dass dieselbe Webhook-Nachricht nicht mehrfach verarbeitet wird. Speichern Sie verarbeitete IDs in einer Datenbank oder einem Cache.

Retry-Logik

Milkee versucht Webhooks automatisch erneut zu senden, wenn:

• Der Endpoint nicht antwortet (Timeout nach 5 Sekunden)
• Ein HTTP-Statuscode außerhalb von 200-299 zurückgegeben wird

Retry-Verhalten:

• Erster Retry: nach 1 Minute
• Zweiter Retry: nach 5 Minuten
• Dritter Retry: nach 15 Minuten
• Vierter Retry: nach 1 Stunde
• Fünfter Retry: nach 6 Stunden

Nach 5 fehlgeschlagenen Versuchen wird der Webhook als fehlgeschlagen markiert.

Sicherheit

HTTPS

Webhook-Endpoints sollten ausschließlich über HTTPS erreichbar sein, um die Sicherheit der übertragenen Daten zu gewährleisten.

IP-Whitelist

Optional können Sie den Zugriff auf bekannte Milkee-IP-Adressen beschränken.

Fehlerbehebung

Webhook kommt nicht an

• Überprüfen Sie, ob Ihre URL öffentlich über HTTPS erreichbar ist
• Stellen Sie sicher, dass eingehende Requests erlaubt sind (Firewall-Regeln)
• Prüfen Sie die Server-Logs auf Fehler
• Antworten Sie innerhalb von 5 Sekunden mit Status 200

Duplikate

Implementieren Sie Idempotenz über webhook_id und speichern Sie verarbeitete IDs in einer Datenbank oder einem Cache.

Performance

Verarbeiten Sie Webhooks asynchron und antworten Sie sofort mit Status 200, bevor Sie die eigentliche Verarbeitung starten.