Ereignisreferenz

Jede Webhook-Anfrage enthält ein Ereignis in einem einheitlichen Umschlag. Diese Seite listet die Ereignistypen, die Felder des Umschlags, die in data gesendeten Objekte und einen Beispiel-Payload für jedes Ereignis auf.

API-Version

Payload-API-Version: 2026-10, gesendet im Feld apiVersion. Neue Felder können hinzukommen, ohne dass sich die Version ändert. Ignorieren Sie daher Felder, die Sie nicht kennen.

Ereignistypen

Ereignistypen haben die Form resource.action, wobei die Aktion in camelCase geschrieben ist. Beim Anlegen oder Bearbeiten eines Webhooks wählen Sie aus, welche Ereignistypen er erhält.

Ereignistyp	Bezeichnung in BeepClock	Wird gesendet, wenn
`timeEntry.created`	Eintrag erfasst	ein Zeiteintrag erfasst wird: an einem Gerät, manuell, automatisch (automatischer Ausgang) oder beim Ergänzen eines fehlenden Eintrags.
`timeEntry.typeChanged`	Eintragstyp geändert	der Typ eines bestehenden Eintrags geändert wird.
`timeEntry.deleted`	Eintrag gelöscht	ein Eintrag gelöscht wird.
`employee.created`	Mitarbeiter hinzugefügt	ein Mitarbeiter in BeepClock angelegt oder von einem Gerät importiert wird.
`employee.updated`	Mitarbeiterdaten geändert	sich Vorname, Nachname, Mitarbeiternummer oder Position ändern.
`employee.archived`	Mitarbeiter archiviert	ein Mitarbeiter archiviert wird.
`employee.unarchived`	Mitarbeiter wiederhergestellt	ein archivierter Mitarbeiter wiederhergestellt wird.
`employee.deleted`	Mitarbeiter gelöscht	ein Mitarbeiter gelöscht wird.
`device.created`	Gerät hinzugefügt	ein Gerät zum Konto hinzugefügt wird.
`device.updated`	Gerätedaten geändert	ein Gerät umbenannt wird, sich seine Beschreibung ändert oder es einem Standort zugeordnet wird.
`device.deleted`	Gerät gelöscht	ein Gerät gelöscht wird.
`webhook.test`	—	ein Testereignis über Testereignis senden gesendet wird. Es kann nicht ausgewählt werden und ist immer verfügbar.

Mehrere schnell aufeinanderfolgende Änderungen desselben Objekts können zu einer Zustellung zusammengefasst werden. Wiederholte employee.updated-, device.updated- oder timeEntry.typeChanged-Ereignisse, die gemeinsam verarbeitet werden, ergeben eine einzige Zustellung, und eine Änderung, die zusammen mit dem created-Ereignis des Objekts verarbeitet wird, ergibt nur die created-Zustellung, die bereits die geänderten Daten enthält.

Ereignisumschlag

{
  "id": "8f2c6a1d-4e7b-5c93-a0d5-1b8e3f6c9a24",
  "event": "timeEntry.created",
  "occurredAt": "2026-10-12T06:58:12Z",
  "tenant": "acme-3f9c1a7b2e4d6f80",
  "apiVersion": "2026-10",
  "data": { }
}

Feld	Beschreibung
`id`	Zustell-ID, entspricht dem Header `X-BeepClock-Delivery`. Verwenden Sie sie, um Duplikate zu erkennen.
`event`	Ereignistyp, entspricht dem Header `X-BeepClock-Event`.
`occurredAt`	Zeitpunkt des Quellereignisses in UTC (ISO 8601 mit dem Suffix `Z`).
`tenant`	Kennung des BeepClock-Kontos.
`apiVersion`	Version des Payload-Vertrags, `2026-10`.
`data`	Das Objekt, das das Ereignis betrifft. Seine Felder hängen von der Ressource ab und sind unten beschrieben.

Ihr Empfänger muss mit folgenden Serialisierungsregeln umgehen können:

Feldnamen und Enum-Werte sind in camelCase geschrieben;
Felder ohne Wert werden weggelassen, ein fehlendes Feld bedeutet also null;
existiert das Objekt beim Vorbereiten der Zustellung nicht mehr, zum Beispiel ein gelöschter Mitarbeiter oder ein gelöschtes Gerät, enthält data nur id;
data beschreibt das Objekt in dem Zustand, in dem BeepClock die Zustellung vorbereitet hat, in der Regel wenige Sekunden nach dem Ereignis;
der Anfragetext ist kompaktes JSON, und manche Zeichen, etwa + oder Nicht-ASCII-Buchstaben, können als \uXXXX-Escape-Sequenzen gesendet werden. Lesen Sie den Anfragetext mit einem JSON-Parser und prüfen Sie die Signatur auf den unveränderten Bytes.

Objekte in `data`

Zeiteintrag

Wird mit timeEntry.*-Ereignissen gesendet.

Feld	Beschreibung
`id`	Kennung des Zeiteintrags.
`employee`	Der Mitarbeiter: `id` (fehlt, wenn die Mitarbeiternummer in BeepClock nicht bekannt ist), `numericId` (Mitarbeiternummer am Gerät), `firstName`, `lastName`.
`eventType`	Eintragstyp: `in`, `out`, `dutyOn`, `dutyOff`, `overtimeOn`, `overtimeOff`, `goOutOn`, `goOutOff`.
`direction`	`in` für `in`, `dutyOn`, `overtimeOn` und `goOutOff`; `out` für `out`, `dutyOff`, `overtimeOff` und `goOutOn`.
`source`	`device` (an einem Gerät erfasst), `manual` (in BeepClock hinzugefügt) oder `automatic` (von BeepClock hinzugefügt, zum Beispiel ein automatischer Ausgang).
`time`	Zeitpunkt des Eintrags in der Zeitzone des Eintrags, ISO 8601 mit Offset.
`timeZone`	IANA-Zeitzone des Eintrags, zum Beispiel `Europe/Warsaw`.
`device`	Gerät, an dem der Eintrag erfasst wurde: `id`, `name`. Nur bei Geräteeinträgen.
`location`	Standort, an dem der Eintrag erfasst wurde. Nur bei Geräteeinträgen, die an einem Standort erfasst wurden.
`previousEntryId`	Der vorherige Eintrag des Mitarbeiters, auf den dieser Eintrag folgt, sofern vorhanden.
`comment`	Kommentar eines manuell hinzugefügten Eintrags.
`deletedAt`	Zeitpunkt der Löschung. Nur in `timeEntry.deleted`.
`deletionComment`	Beim Löschen angegebener Grund. Nur in `timeEntry.deleted`.

timeEntry.typeChanged enthält den Eintrag mit dem neuen eventType und der neuen direction. timeEntry.deleted enthält den Eintrag im bisherigen Zustand sowie deletedAt und deletionComment.

Mitarbeiter

Wird mit employee.*-Ereignissen gesendet.

Feld	Beschreibung
`id`	Kennung des Mitarbeiters.
`numericId`	An den Geräten verwendete Mitarbeiternummer.
`firstName`, `lastName`	Vor- und Nachname.
`position`	Position, sofern angegeben.
`archived`	`true`, wenn der Mitarbeiter archiviert ist, sonst `false`.
`archivedAt`	Zeitpunkt der Archivierung.

employee.deleted enthält nur id.

Gerät

Wird mit device.*-Ereignissen gesendet.

Feld	Beschreibung
`id`	Kennung des Geräts.
`name`	Gerätename.
`description`	Beschreibung, sofern angegeben.
`serialNumber`	Seriennummer des Geräts.
`location`	Standort, dem das Gerät zugeordnet ist.

device.deleted enthält nur id.

Standort

Feld	Beschreibung
`id`	Kennung des Standorts.
`name`	Name des Standorts.
`archived`	`true`, wenn der Standort archiviert ist; sonst wird das Feld weggelassen.
`path`	Die Standorthierarchie von der obersten Ebene bis zu diesem Standort (einschließlich), jedes Element mit `id` und `name`.

Wurde der Standort gelöscht, wird nur id gesendet.

Test

Wird mit webhook.test gesendet.

Feld	Beschreibung
`webhookId`	Kennung des Webhooks, für den der Test gesendet wurde.

Beispiel-Payloads

Die Beispiele sind zur besseren Lesbarkeit formatiert. Der Anfragetext ist kompaktes JSON und kann \uXXXX-Escape-Sequenzen enthalten, zum Beispiel \u002B für + in einem Zeitzonen-Offset. Jeder JSON-Parser liest beide Formen gleich.

`timeEntry.created`

Ein Eintrag, der an einem Gerät an einem Standort erfasst wurde:

{
  "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": [
        {
          "id": "6d1f8a52-3c47-4b0e-9a61-2f5c8e7d4b10",
          "name": "Krakow plant"
        },
        {
          "id": "b2e4c7a9-58d1-4f36-8c0b-71a3e9f2d645",
          "name": "Hall B"
        }
      ]
    },
    "previousEntryId": "4a8d2f6c-1e93-4b7a-9c05-8f3e6b2d1a94"
  }
}

`timeEntry.created`: manueller Eintrag

Ein in BeepClock hinzugefügter Eintrag mit Kommentar:

{
  "id": "2d7a9e4b-6c18-5f35-b9e2-4a1c7d3f8b60",
  "event": "timeEntry.created",
  "occurredAt": "2026-10-12T06:58:12Z",
  "tenant": "acme-3f9c1a7b2e4d6f80",
  "apiVersion": "2026-10",
  "data": {
    "id": "1f5e9b3c-7d24-4a86-b1e0-9c4f2a7d6e58",
    "employee": {
      "id": "3b6f2d1e-8c4a-4e57-b9d0-5a7c1f3e2b84",
      "numericId": 17,
      "firstName": "Anna",
      "lastName": "Nowak"
    },
    "eventType": "dutyOff",
    "direction": "out",
    "source": "manual",
    "time": "2026-10-11T16:00:00+02:00",
    "timeZone": "Europe/Warsaw",
    "comment": "Forgot to clock out"
  }
}

`timeEntry.typeChanged`

{
  "id": "5e1b8d3a-9f46-5a27-8c0e-7d2f4b6a1c93",
  "event": "timeEntry.typeChanged",
  "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": "dutyOn",
    "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": [
        {
          "id": "6d1f8a52-3c47-4b0e-9a61-2f5c8e7d4b10",
          "name": "Krakow plant"
        },
        {
          "id": "b2e4c7a9-58d1-4f36-8c0b-71a3e9f2d645",
          "name": "Hall B"
        }
      ]
    },
    "previousEntryId": "4a8d2f6c-1e93-4b7a-9c05-8f3e6b2d1a94"
  }
}

`timeEntry.deleted`

{
  "id": "a3c7f1e9-2b5d-5846-9e0a-6f4d8b2c7e15",
  "event": "timeEntry.deleted",
  "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": [
        {
          "id": "6d1f8a52-3c47-4b0e-9a61-2f5c8e7d4b10",
          "name": "Krakow plant"
        },
        {
          "id": "b2e4c7a9-58d1-4f36-8c0b-71a3e9f2d645",
          "name": "Hall B"
        }
      ]
    },
    "previousEntryId": "4a8d2f6c-1e93-4b7a-9c05-8f3e6b2d1a94",
    "deletedAt": "2026-10-12T09:15:00+00:00",
    "deletionComment": "Duplicate entry"
  }
}

`employee.created`

{
  "id": "6b4e2a8c-1d97-5f3b-a2c6-9e5f1d7b3a48",
  "event": "employee.created",
  "occurredAt": "2026-10-12T06:58:12Z",
  "tenant": "acme-3f9c1a7b2e4d6f80",
  "apiVersion": "2026-10",
  "data": {
    "id": "3b6f2d1e-8c4a-4e57-b9d0-5a7c1f3e2b84",
    "numericId": 17,
    "firstName": "Anna",
    "lastName": "Nowak",
    "position": "Warehouse operator",
    "archived": false
  }
}

`employee.updated`

{
  "id": "d9f3b7e1-5a2c-5468-8b4d-2c6e9a1f5d37",
  "event": "employee.updated",
  "occurredAt": "2026-10-12T06:58:12Z",
  "tenant": "acme-3f9c1a7b2e4d6f80",
  "apiVersion": "2026-10",
  "data": {
    "id": "3b6f2d1e-8c4a-4e57-b9d0-5a7c1f3e2b84",
    "numericId": 17,
    "firstName": "Anna",
    "lastName": "Nowak",
    "position": "Warehouse operator",
    "archived": false
  }
}

`employee.archived`

{
  "id": "1c8e5b2f-7a43-5d96-b0e7-4f2a6c9d1b85",
  "event": "employee.archived",
  "occurredAt": "2026-10-12T06:58:12Z",
  "tenant": "acme-3f9c1a7b2e4d6f80",
  "apiVersion": "2026-10",
  "data": {
    "id": "3b6f2d1e-8c4a-4e57-b9d0-5a7c1f3e2b84",
    "numericId": 17,
    "firstName": "Anna",
    "lastName": "Nowak",
    "position": "Warehouse operator",
    "archived": true,
    "archivedAt": "2026-10-12T06:58:11+00:00"
  }
}

`employee.unarchived`

{
  "id": "7e2a9d4c-3b61-5f8e-9a5c-1d7b3e8f2a06",
  "event": "employee.unarchived",
  "occurredAt": "2026-10-12T06:58:12Z",
  "tenant": "acme-3f9c1a7b2e4d6f80",
  "apiVersion": "2026-10",
  "data": {
    "id": "3b6f2d1e-8c4a-4e57-b9d0-5a7c1f3e2b84",
    "numericId": 17,
    "firstName": "Anna",
    "lastName": "Nowak",
    "position": "Warehouse operator",
    "archived": false
  }
}

`employee.deleted`

{
  "id": "4f6c1a8e-9d25-5b73-8e1f-7a3c5b9d2e64",
  "event": "employee.deleted",
  "occurredAt": "2026-10-12T06:58:12Z",
  "tenant": "acme-3f9c1a7b2e4d6f80",
  "apiVersion": "2026-10",
  "data": {
    "id": "3b6f2d1e-8c4a-4e57-b9d0-5a7c1f3e2b84"
  }
}

`device.created`

{
  "id": "b8d2e6a3-4c19-5f57-a3b8-5e9c2f7a1d46",
  "event": "device.created",
  "occurredAt": "2026-10-12T06:58:12Z",
  "tenant": "acme-3f9c1a7b2e4d6f80",
  "apiVersion": "2026-10",
  "data": {
    "id": "9c3a7e15-2f6b-4d84-a0e9-6b1d5c8f3a27",
    "name": "Main entrance",
    "description": "Gate 1, ground floor",
    "serialNumber": "AEYU201060123",
    "location": {
      "id": "b2e4c7a9-58d1-4f36-8c0b-71a3e9f2d645",
      "name": "Hall B",
      "path": [
        {
          "id": "6d1f8a52-3c47-4b0e-9a61-2f5c8e7d4b10",
          "name": "Krakow plant"
        },
        {
          "id": "b2e4c7a9-58d1-4f36-8c0b-71a3e9f2d645",
          "name": "Hall B"
        }
      ]
    }
  }
}

`device.updated`

{
  "id": "3a9f5c7b-8e24-5d61-b6a3-2f8d4e1c9b70",
  "event": "device.updated",
  "occurredAt": "2026-10-12T06:58:12Z",
  "tenant": "acme-3f9c1a7b2e4d6f80",
  "apiVersion": "2026-10",
  "data": {
    "id": "9c3a7e15-2f6b-4d84-a0e9-6b1d5c8f3a27",
    "name": "Main entrance",
    "description": "Gate 1, ground floor",
    "serialNumber": "AEYU201060123",
    "location": {
      "id": "b2e4c7a9-58d1-4f36-8c0b-71a3e9f2d645",
      "name": "Hall B",
      "path": [
        {
          "id": "6d1f8a52-3c47-4b0e-9a61-2f5c8e7d4b10",
          "name": "Krakow plant"
        },
        {
          "id": "b2e4c7a9-58d1-4f36-8c0b-71a3e9f2d645",
          "name": "Hall B"
        }
      ]
    }
  }
}

`device.deleted`

{
  "id": "f1e7a3d9-6b52-5c84-9d2a-8b4e6c1f3a29",
  "event": "device.deleted",
  "occurredAt": "2026-10-12T06:58:12Z",
  "tenant": "acme-3f9c1a7b2e4d6f80",
  "apiVersion": "2026-10",
  "data": {
    "id": "9c3a7e15-2f6b-4d84-a0e9-6b1d5c8f3a27"
  }
}

`webhook.test`

{
  "id": "0b9e6c41-5d2a-4f78-93e1-c6a8b2f4d071",
  "event": "webhook.test",
  "occurredAt": "2026-10-12T06:58:12Z",
  "tenant": "acme-3f9c1a7b2e4d6f80",
  "apiVersion": "2026-10",
  "data": {
    "webhookId": "c5d8a2e7-4b19-4f63-8a0d-3e7b9c1f6a52"
  }
}

Ereignistypen​

Ereignisumschlag​

Objekte in data​

Zeiteintrag​

Mitarbeiter​

Gerät​

Standort​

Test​

Beispiel-Payloads​

timeEntry.created​

timeEntry.created: manueller Eintrag​

timeEntry.typeChanged​

timeEntry.deleted​

employee.created​

employee.updated​

employee.archived​

employee.unarchived​

employee.deleted​

device.created​

device.updated​

device.deleted​

webhook.test​