Webhooks

Zusatzfunktion

Webhooks sind eine Zusatzfunktion

Webhooks sind nicht in den Standardtarifen von BeepClock enthalten und stehen erst zur Verfügung, wenn BeepClock sie für Ihr Konto aktiviert. Zur Aktivierung wenden Sie sich an BeepClock unter [email protected]. Bis dahin erscheint Webhooks nicht im Menü. Siehe Verfügbarkeit.

Webhooks senden BeepClock-Ereignisse an Ihr eigenes System, sobald sie eintreten: Zeiteinträge, die an einem TimeLok-Terminal erfasst oder in der App hinzugefügt werden, sowie Änderungen an Mitarbeitern und Geräten. Ihr Lohnabrechnungs-, HR- oder Integrationssystem erhält jedes Ereignis als signierte HTTPS-POST-Anfrage. Sie müssen BeepClock also weder regelmäßig abfragen noch Berichte von Hand exportieren.

So funktioniert es

1. Sie fügen in BeepClock einen Webhook hinzu: die URL Ihres Endpunkts und die Ereignisse, die Sie erhalten möchten.
2. Tritt eines dieser Ereignisse ein, sendet BeepClock einen JSON-Payload an den Endpunkt und signiert ihn mit dem Signaturgeheimnis des Webhooks.
3. Ihr Endpunkt prüft die Signatur, speichert das Ereignis und antwortet innerhalb von 10 Sekunden mit einem 2xx-Status.
4. Antwortet der Endpunkt nicht erfolgreich, wiederholt BeepClock die Zustellung etwa anderthalb Tage lang. Jede Zustellung ist 30 Tage lang im Zustellprotokoll des Webhooks sichtbar.

Beispiel: Ein Mitarbeiter stempelt an einem Terminal ein

{
  "id": "8f2c6a1d-4e7b-5c93-a0d5-1b8e3f6c9a24",
  "event": "timeEntry.created",
  "occurredAt": "2026-10-12T06:58:12Z",
  "tenant": "acme-3f9c1a7b2e4d6f80",
  "apiVersion": "2026-10",
  "data": {
    "id": "e7b1c4d2-9a35-4f68-8e0c-2d6a9f1b5c73",
    "employee": {
      "id": "3b6f2d1e-8c4a-4e57-b9d0-5a7c1f3e2b84",
      "numericId": 17,
      "firstName": "Anna",
      "lastName": "Nowak"
    },
    "eventType": "in",
    "direction": "in",
    "source": "device",
    "time": "2026-10-12T08:58:10+02:00",
    "timeZone": "Europe/Warsaw",
    "device": {
      "id": "9c3a7e15-2f6b-4d84-a0e9-6b1d5c8f3a27",
      "name": "Main entrance"
    },
    "location": {
      "id": "b2e4c7a9-58d1-4f36-8c0b-71a3e9f2d645",
      "name": "Hall B",
      "path": [ … ]
    }
  }
}

Verfügbare Ereignisse

Ressource	Ereignisse
Zeiteinträge	timeEntry.created, timeEntry.typeChanged, timeEntry.deleted
Mitarbeiter	employee.created, employee.updated, employee.archived, employee.unarchived, employee.deleted
Geräte	device.created, device.updated, device.deleted

Geräteereignisse und an einem Gerät erfasste Zeiteinträge enthalten den Standort mit seiner vollständigen Hierarchie, zum Beispiel Krakow plant → Hall B. Vollständige Payloads ansehen.

Verfügbarkeit

Webhooks sind eine Zusatzfunktion. Sie sind nicht Teil der Standardtarife von BeepClock: BeepClock aktiviert sie für jedes Konto einzeln. Um Webhooks zu nutzen, wenden Sie sich an BeepClock unter [email protected] und bitten Sie darum, Webhooks für Ihr Konto zu aktivieren.

Nach der Aktivierung erscheint Webhooks im Menü von app.beepclock.com, und jeder Benutzer des Kontos kann Webhooks verwalten.

Weiterführende Seiten

• Webhook einrichten: einen Webhook anlegen, das Signaturgeheimnis speichern und ein Testereignis senden.
• Ereignisreferenz: der Ereignisumschlag, alle Ereignistypen und die Felder jedes Objekts, mit Beispiel-Payloads.
• Signaturen prüfen: der Signaturalgorithmus, einsatzbereiter Code für Node.js und C# sowie die Rotation des Geheimnisses.
• Zustellungen und Wiederholungen: Anfrage-Header, Wiederholungsplan, automatisches Pausieren, Zustellprotokoll und erneutes Senden.
• Best Practices für Empfänger: eine Checkliste für einen zuverlässigen und sicheren Endpunkt.

Häufig gestellte Fragen

Wie aktiviere ich Webhooks für mein Konto?

Webhooks sind eine Zusatzfunktion, die BeepClock für jedes Konto einzeln aktiviert. Wenden Sie sich an BeepClock unter [email protected] und bitten Sie um die Aktivierung. Danach erscheint Webhooks im Menü der Anwendung.

Wofür kann ich BeepClock-Webhooks verwenden?

Um Zeiteinträge zeitnah an ein Lohnabrechnungs- oder HR-System zu übergeben, um eine Mitarbeiter- oder Geräteliste mit einer anderen Anwendung synchron zu halten oder um eigene Automatisierungen auszulösen, zum Beispiel eine Benachrichtigung, wenn ein Mitarbeiter an einem bestimmten Standort einstempelt.

Brauche ich einen Entwickler, um Webhooks zu nutzen?

Ja, oder eine Integrationsplattform, die HTTPS-Anfragen empfangen kann. Der Endpunkt muss POST-Anfragen annehmen, die Signatur prüfen und innerhalb von 10 Sekunden antworten. Die Einrichtung in BeepClock selbst dauert nur wenige Minuten.

Werden Ereignisse erneut gesendet, wenn mein System nicht erreichbar war?

Ja. Eine fehlgeschlagene Zustellung wird etwa 35 Stunden lang wiederholt, mit insgesamt bis zu 7 Versuchen. Außerdem können Sie jede Zustellung 30 Tage lang aus dem Zustellprotokoll erneut senden. Schlägt die Zustellung an den Endpunkt dauerhaft fehl, pausiert BeepClock den Webhook und benachrichtigt die Benutzer des Kontos per E-Mail.

Werden Webhooks für Ereignisse gesendet, die vor dem Anlegen des Webhooks eingetreten sind?

Nein. Ein Webhook erhält nur Ereignisse, die eintreten, während er aktiv ist. Ereignisse, die eintreten, während ein Webhook pausiert ist, werden auch nicht nachträglich zugestellt.

Kann ich einen Webhook auf einen Standort beschränken?

Noch nicht. Ein Webhook erhält die ausgewählten Ereignisse aus dem gesamten Konto. Geräteereignisse und an einem Gerät erfasste Zeiteinträge enthalten den Standort und seine Hierarchie, sodass Ihr System danach filtern kann.