Zum Hauptinhalt springen

Webhook einrichten

Zusatzfunktion

Webhooks sind eine Zusatzfunktion, die BeepClock für jedes Konto einzeln aktiviert. Wenn Webhooks im Menü fehlt, wenden Sie sich zur Aktivierung an BeepClock unter [email protected]. Siehe Verfügbarkeit.

Diese Anleitung führt Sie in wenigen Minuten von einem leeren Endpunkt zu einem funktionierenden Webhook. Sie benötigen einen HTTPS-Endpunkt, der POST-Anfragen annimmt; auf der Seite zur Signaturprüfung finden Sie einen vollständigen Empfänger in Node.js und C#, auf dem Sie aufbauen können.

1. Endpunkt vorbereiten​

Der Endpunkt muss:

  • https verwenden und aus dem Internet erreichbar sein. Adressen in privaten Netzen (10.x, 192.168.x, localhost und ähnliche) werden abgelehnt.
  • innerhalb von 10 Sekunden mit einem beliebigen 2xx-Status antworten. Weiterleitungen werden nicht verfolgt.
Test auf dem eigenen Rechner

Um Webhooks auszuprobieren, bevor Sie den Empfänger bereitstellen, machen Sie einen lokalen Server über einen HTTPS-Tunnel erreichbar, zum Beispiel mit ngrok oder Cloudflare Tunnel, und verwenden Sie die öffentliche Adresse des Tunnels als Endpunkt-URL.

2. Webhook anlegen​

  1. Öffnen Sie Webhooks im BeepClock-Menü und wählen Sie Webhook hinzufügen.
  2. Geben Sie unter Name eine Bezeichnung ein, zum Beispiel den Namen des empfangenden Systems, und unter Endpunkt-URL die Adresse Ihres Endpunkts.
  3. Wählen Sie unter Ereignisse die zu sendenden Ereignisse aus. Sie sind nach Zeiteinträgen, Mitarbeitern und Geräten gruppiert; die Ereignisreferenz erklärt, wann jedes Ereignis gesendet wird.
  4. Fügen Sie bei Bedarf unter Eigene Header Header hinzu, die Ihr Endpunkt erwartet, zum Beispiel Authorization: Bearer …. Ein Webhook kann höchstens 10 eigene Header haben. Ihre Werte werden verschlüsselt gespeichert und nicht erneut angezeigt.
  5. Wählen Sie Speichern.

3. Signaturgeheimnis speichern​

Nach dem Speichern zeigt BeepClock das Signaturgeheimnis an, eine Zeichenkette, die mit whsec_ beginnt. Es wird nur einmal angezeigt. Kopieren Sie es und hinterlegen Sie es in der Konfiguration Ihres Systems, zum Beispiel als Umgebungsvariable BEEPCLOCK_WEBHOOK_SECRET. Ihr Endpunkt verwendet es, um zu prüfen, ob Anfragen von BeepClock stammen.

Wenn Sie das Geheimnis verlieren, wählen Sie im Menü des Webhooks Neues Signaturgeheimnis erzeugen. Das bisherige Geheimnis bleibt 24 Stunden lang gültig, sodass Sie es ohne Unterbrechung rotieren können.

4. Testereignis senden​

Öffnen Sie den Webhook und wählen Sie Testereignis senden. BeepClock sendet sofort ein signiertes Ereignis webhook.test und zeigt den HTTP-Status und die Antwortzeit Ihres Endpunkts an.

Ein Testereignis wird einmal gesendet, nie wiederholt und erscheint nicht im Zustellprotokoll. Sie können es auch senden, während der Webhook pausiert ist, um den Endpunkt vor dem Fortsetzen zu prüfen.

5. Echte Zustellungen verfolgen​

Erfassen Sie einen Zeiteintrag an einem Terminal oder ändern Sie einen Mitarbeiter oder ein Gerät, und öffnen Sie den Webhook erneut. Das Zustellprotokoll listet jede Zustellung der letzten 30 Tage mit ihrem Status, der Anzahl der Versuche und der letzten Antwort auf. Wählen Sie eine Zustellung aus, um jeden Versuch mit HTTP-Status, Dauer und Fehler sowie den genau gesendeten Payload zu sehen.

Ist eine Zustellung fehlgeschlagen, beheben Sie das Problem am Endpunkt und wählen Sie Erneut senden. BeepClock sendet denselben Payload mit derselben Zustell-ID, sodass Ihr System die Zustellung wiedererkennen kann. Das vollständige Verhalten beschreibt Zustellungen und Wiederholungen.

Webhooks verwalten​

In der Webhook-Liste und auf der Seite des Webhooks stehen folgende Aktionen zur Verfügung:

AktionWirkung
BearbeitenName, URL, Ereignisse oder eigene Header ändern. Lassen Sie den Wert eines eigenen Headers leer, um den gespeicherten Wert zu behalten.
Senden pausieren / Senden fortsetzenZustellungen anhalten und wieder aufnehmen. Ereignisse, die eintreten, während ein Webhook pausiert ist, werden nicht nachträglich gesendet.
Neues Signaturgeheimnis erzeugenEin neues Geheimnis erstellen. In den nächsten 24 Stunden werden Anfragen mit beiden Geheimnissen signiert.
Webhook löschenDen Webhook entfernen. Zustellungen, die noch auf eine Wiederholung warten, werden nicht gesendet.

Nächste Schritte​