Webhooks

Senden Sie Ereignisse in Echtzeit an externe Systeme. Verbinden Sie Fesk mit Ihren eigenen Tools, Dashboards oder Automatisierungspipelines.

Einrichtung

Gehen Sie zu Einstellungen → Ausgehende Webhooks und klicken Sie auf Webhook hinzufügen (Admin-Rolle erforderlich). Sie benötigen:

• Projekt: das Projekt, dessen Ereignisse gesendet werden
• Webhook-URL: der Endpunkt, der Ereignisse empfängt. HTTPS wird empfohlen, damit niemand die Daten unterwegs mitlesen kann; einfaches HTTP wird akzeptiert. Eine Adresse in einem privaten oder internen Netz wird abgewiesen
• Ereignisse: welche Ereignisse abonniert werden sollen
• Webhook-Geheimnis (optional): ein HMAC-Schlüssel zur Signaturprüfung. Lassen Sie das Feld leer, erzeugt Fesk einen

Nach dem Anlegen zeigt Fesk das Secret für die Signatur. Es wird nur dieses eine Mal angezeigt, kopieren Sie es also gleich.

Dieselbe Seite listet jeden Webhook der Projekte des Kontos, gleich wer ihn angelegt hat, mit seiner letzten fehlgeschlagenen Zustellung. Admins können jeden davon dort deaktivieren, wieder aktivieren oder löschen.

Ein Webhook lässt sich auch über die API anlegen, mit POST /v1/webhooks und einem API-Key, der den Scope tickets:write hat (Keys erzeugen Sie unter Einstellungen → API-Schlüssel):

curl -X POST https://api.fesk.io/v1/webhooks \
  -H "Authorization: Bearer ld_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-server.com/fesk-webhook", "events": ["ticket.created", "comment.created"], "project_id": 1}'

Mit einem projektgebundenen Key kann project_id entfallen: der Webhook entsteht im Projekt des Keys. Die Antwort enthält das Secret für die Signatur, einmalig. Anfrage und Antwort stehen vollständig in der API-Referenz.

Einen Webhook testen

Test senden bei einem Webhook unter Einstellungen → Ausgehende Webhooks schickt eine Anfrage an dessen URL und zeigt den Status, mit dem Ihr Endpunkt geantwortet hat. Über die API ist das POST /v1/webhooks/{id}/test.

Der Test ist signiert und trägt die Header einer echten Zustellung, sodass Ihre Signaturprüfung mitgeprüft wird. Sein Ereignis ist webhook.test, das kein Webhook abonniert, und er enthält kein Ticket: Ein Endpunkt, der auf Ticket-Ereignisse reagiert, tut damit nichts. Ein Test wird nicht wiederholt und zählt nicht zu den fehlgeschlagenen Zustellungen, und ein deaktivierter Webhook lässt sich testen, bevor er wieder eingeschaltet wird.

Verfügbare Ereignisse

| Ereignis | Wird ausgelöst, wenn | |----------|---------------------| | ticket.created | Ein neues Ticket erstellt wird | | ticket.updated | Ticket-Felder sich ändern (Titel, Beschreibung, Priorität, Tags) | | ticket.deleted | Ein Ticket gelöscht wird | | ticket.status_changed | Ein Ticket in einen anderen Status wechselt | | ticket.assigned | Ein Ticket zugewiesen oder neu zugewiesen wird | | ticket.merged | Tickets zu einem zusammengeführt werden | | comment.created | Ein öffentlicher Kommentar zu einem Ticket hinzugefügt wird (interne Notizen senden kein Ereignis) |

Wählen Sie ein oder mehrere Ereignisse pro Webhook. Sie können mehrere Webhooks mit unterschiedlichen URLs und Ereignis-Sets anlegen.

Payload

Jede Zustellung sendet einen JSON-Payload mit Ereignistyp, Zeitstempel und data. data.ticket ist bei jedem Ereignis das Ticket im aktuellen Zustand. Die Felder des Ereignisses stehen daneben: data.comment bei einem Kommentar, der alte und der neue Status bei einem Statuswechsel, die alte und die neue Zuweisung bei einer Zuweisung. Der Header X-Webhook-Event identifiziert den Ereignistyp.

Signaturprüfung

Jede Zustellung enthält einen X-Webhook-Signature-Header, den HMAC-SHA256-Hex-Digest des rohen Request-Bodys, signiert mit dem Secret Ihres Webhooks. (Wenn Sie beim Anlegen kein Secret angeben, erzeugt Fesk eines und zeigt es einmalig bei der Erstellung an.) Berechnen Sie auf Ihrer Seite HMAC-SHA256(secret, raw_body) und vergleichen Sie, um die Authentizität zu prüfen.

Wiederholungsverhalten

Fehlgeschlagene Zustellungen (kein 2xx-Status oder ein Timeout nach 10 Sekunden) werden bis zu 4-mal wiederholt, also insgesamt 5 Versuche pro Ereignis: 1 Minute, 5 Minuten, 30 Minuten und 2 Stunden nach dem jeweils vorigen Versuch. Ein Endpunkt, der bis zu etwa zweieinhalb Stunden nicht erreichbar ist, erhält das Ereignis trotzdem. Danach wird die Zustellung als fehlgeschlagen protokolliert; das Abonnement bleibt aktiv und empfängt weiterhin künftige Ereignisse, es gibt also kein automatisches Deaktivieren nach wiederholten Fehlern. Es gibt keine Replay-API: Wenn Ihr Endpunkt längere Zeit nicht erreichbar ist, gleichen Sie den Zustand nach der Wiederherstellung durch Abfragen der relevanten Endpunkte ab.