Webhooks

Webhooks lassen Weqly deine eigenen Systeme in Echtzeit benachrichtigen, wenn etwas passiert, etwa das Zuweisen einer Schicht, das Genehmigen einer Abwesenheit oder der Beitritt eines Teamkollegen. Immer wenn ein Ereignis auftritt, das du abonniert hast, sendet Weqly einen HTTP-POST an eine von dir angegebene URL.

Du verwaltest Webhooks auf der Seite Integrationen. (Das Einrichten ist typischerweise eine Aufgabe für Administratoren/Entwickler.)

Einen Webhook erstellen

1. Gehe zu Integrationen und füge einen Webhook hinzu.
2. Gib ihm einen Namen (damit du ihn später wiedererkennst).
3. Gib die URL ein, an die Weqly Ereignisse senden soll. Sie muss ein öffentlicher HTTPS-Endpunkt sein. Interne oder private Adressen werden aus Sicherheitsgründen abgelehnt.
4. Wähle, welche Ereignisse du abonnieren möchtest (mindestens eines).
5. Speichern.

Du kannst einen Webhook als aktiv oder inaktiv kennzeichnen. Inaktive Webhooks empfangen keine Ereignisse mehr, ohne gelöscht zu werden.

Verfügbare Ereignisse

Weqly löst Ereignisse in diesen Bereichen aus:

Bereich	Ereignisse
Abwesenheit	leave.requested, leave.approved, leave.rejected, leave.cancelled
Schicht	shift.assigned, shift.changed, shift.removed
Tausch	trade.requested, trade.approved, trade.rejected, trade.cancelled
Abgabe	drop.requested, drop.approved, drop.rejected, drop.cancelled
Einladung	invite.sent, invite.accepted, invite.expired
Nutzer	user.joined, user.updated, user.removed
Kudos	kudos.sent

Wie eine Zustellung aussieht

Jede Zustellung ist ein POST mit einem JSON-Body, der das Ereignis beschreibt, plus zwei Header:

Header	Zweck
X-Weqly-Event	Der Ereignisname, z. B. shift.assigned.
X-Weqly-Signature	Eine Signatur, mit der du prüfst, dass die Anfrage wirklich von Weqly stammt.

Die Signatur prüfen

Jeder Webhook hat ein Geheimnis (auf dem Webhook in den Integrationen sichtbar). Weqly signiert damit jeden Anfrage-Body, damit du die Echtheit bestätigen und gefälschte Aufrufe ablehnen kannst.

Die Signatur ist:

X-Weqly-Signature: sha256=<HMAC-SHA256 des rohen Anfrage-Bodys, mit deinem Geheimnis als Schlüssel>

So prüfst du auf deiner Seite:

1. Nimm den rohen Anfrage-Body genau so, wie er empfangen wurde.
2. Berechne den HMAC-SHA256 dieses Bodys mit dem Geheimnis deines Webhooks als Schlüssel.
3. Stelle dem Hex-Ergebnis sha256= voran.
4. Vergleiche es mit dem Header X-Weqly-Signature (nutze einen zeitkonstanten Vergleich).

Stimmen sie nicht überein, verwirf die Anfrage.

Hinweise zu Zuverlässigkeit & Sicherheit

• Zustellungen werden als Hintergrundaufgaben gesendet und bei Fehlern erneut versucht.
• URLs werden sowohl beim Speichern als auch erneut beim Senden auf Sicherheit geprüft, um zu verhindern, dass Anfragen auf interne Systeme umgeleitet werden.
• Halte dein Geheimnis vertraulich. Jeder, der es hat, kann signierte Anfragen fälschen.

Brauchst du Hilfe?

Wende dich an unser Support-Team unter help@weqly.com. Wir helfen dir gern.