Dokumentacja zdarzeń

Każde żądanie webhooka zawiera jedno zdarzenie we wspólnej kopercie. Ta strona opisuje typy zdarzeń, pola koperty, obiekty wysyłane w data oraz przykładowy payload każdego zdarzenia.

Wersja API

Wersja API payloadu: 2026-10, wysyłana w polu apiVersion. Nowe pola mogą być dodawane bez zmiany wersji, dlatego ignoruj pola, których nie znasz.

Typy zdarzeń

Typy zdarzeń mają postać resource.action (zasób i akcja), z akcją zapisaną w camelCase. Przy tworzeniu lub edycji webhooka wybierasz, które typy zdarzeń ma otrzymywać.

Typ zdarzenia	Nazwa w BeepClock	Kiedy jest wysyłane
`timeEntry.created`	Zarejestrowano odbicie	Zarejestrowano odbicie: na urządzeniu, ręcznie, automatycznie (automatyczne wyjście) lub przy uzupełnieniu brakującego odbicia.
`timeEntry.typeChanged`	Zmieniono typ odbicia	Zmieniono typ istniejącego odbicia.
`timeEntry.deleted`	Usunięto odbicie	Usunięto odbicie.
`employee.created`	Dodano pracownika	Dodano pracownika w BeepClock lub zaimportowano go z urządzenia.
`employee.updated`	Zmieniono dane pracownika	Zmieniono imię, nazwisko, numer pracownika lub stanowisko.
`employee.archived`	Zarchiwizowano pracownika	Zarchiwizowano pracownika.
`employee.unarchived`	Przywrócono pracownika	Przywrócono zarchiwizowanego pracownika.
`employee.deleted`	Usunięto pracownika	Usunięto pracownika.
`device.created`	Dodano urządzenie	Dodano urządzenie do konta.
`device.updated`	Zmieniono dane urządzenia	Zmieniono nazwę lub opis urządzenia albo przypisano je do lokalizacji.
`device.deleted`	Usunięto urządzenie	Usunięto urządzenie.
`webhook.test`	—	Zdarzenie testowe wysyłane przyciskiem Wyślij zdarzenie testowe. Nie można go wybrać; jest zawsze dostępne.

Kilka szybkich zmian tego samego obiektu może zostać połączonych w jedno dostarczenie. Powtórzone zdarzenia employee.updated, device.updated lub timeEntry.typeChanged przetworzone razem dają jedno dostarczenie, a zmiana przetworzona razem ze zdarzeniem created tego obiektu daje tylko dostarczenie created, już z nowymi danymi.

Koperta zdarzenia

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

Pole	Opis
`id`	Identyfikator dostarczenia, równy nagłówkowi `X-BeepClock-Delivery`. Służy do wykrywania duplikatów.
`event`	Typ zdarzenia, równy nagłówkowi `X-BeepClock-Event`.
`occurredAt`	Czas wystąpienia zdarzenia źródłowego w UTC (ISO 8601 z sufiksem `Z`).
`tenant`	Identyfikator konta BeepClock.
`apiVersion`	Wersja kontraktu payloadu, `2026-10`.
`data`	Obiekt, którego dotyczy zdarzenie. Jego pola zależą od zasobu i są opisane poniżej.

Odbiorca musi być odporny na następujące zasady serializacji:

nazwy pól i wartości enumów są zapisywane w camelCase;
pola bez wartości są pomijane, więc brak pola oznacza null;
jeśli obiekt już nie istnieje w chwili przygotowania dostarczenia, np. usunięty pracownik lub urządzenie, data zawiera tylko id;
data opisuje obiekt w stanie z chwili, gdy BeepClock przygotował dostarczenie, zwykle w ciągu kilku sekund od zdarzenia;
ciało jest zwartym JSON-em, a niektóre znaki, takie jak + czy litery spoza ASCII, mogą być zapisane jako sekwencje \uXXXX. Ciało odczytuj parserem JSON, a podpis weryfikuj na surowych bajtach.

Obiekty w `data`

Odbicie

Obiekt wysyłany ze zdarzeniami timeEntry.*.

Pole	Opis
`id`	Identyfikator odbicia.
`employee`	Pracownik: `id` (pomijane, gdy numer pracownika nie jest znany w BeepClock), `numericId` (numer pracownika na urządzeniu), `firstName`, `lastName`.
`eventType`	Typ odbicia: `in`, `out`, `dutyOn`, `dutyOff`, `overtimeOn`, `overtimeOff`, `goOutOn`, `goOutOff`.
`direction`	`in` dla `in`, `dutyOn`, `overtimeOn` i `goOutOff`; `out` dla `out`, `dutyOff`, `overtimeOff` i `goOutOn`.
`source`	`device` (zarejestrowane na urządzeniu), `manual` (dodane w BeepClock) lub `automatic` (dodane przez BeepClock, np. automatyczne wyjście).
`time`	Czas odbicia w strefie czasowej odbicia, ISO 8601 z przesunięciem.
`timeZone`	Strefa czasowa IANA odbicia, np. `Europe/Warsaw`.
`device`	Urządzenie, na którym zarejestrowano odbicie: `id`, `name`. Tylko dla odbić z urządzenia.
`location`	Lokalizacja, w której zarejestrowano odbicie. Tylko dla odbić z urządzenia zarejestrowanych w lokalizacji.
`previousEntryId`	Poprzednie odbicie pracownika, po którym nastąpiło to odbicie, jeśli istnieje.
`comment`	Komentarz do odbicia dodanego ręcznie.
`deletedAt`	Czas usunięcia odbicia. Tylko w `timeEntry.deleted`.
`deletionComment`	Powód podany przy usuwaniu odbicia. Tylko w `timeEntry.deleted`.

timeEntry.typeChanged zawiera odbicie z nowymi wartościami eventType i direction. timeEntry.deleted zawiera odbicie w dotychczasowej postaci oraz deletedAt i deletionComment.

Pracownik

Obiekt wysyłany ze zdarzeniami employee.*.

Pole	Opis
`id`	Identyfikator pracownika.
`numericId`	Numer pracownika używany na urządzeniach.
`firstName`, `lastName`	Imię i nazwisko.
`position`	Stanowisko, jeśli zostało podane.
`archived`	`true`, jeśli pracownik jest zarchiwizowany, w przeciwnym razie `false`.
`archivedAt`	Czas archiwizacji pracownika.

employee.deleted zawiera tylko id.

Urządzenie

Obiekt wysyłany ze zdarzeniami device.*.

Pole	Opis
`id`	Identyfikator urządzenia.
`name`	Nazwa urządzenia.
`description`	Opis, jeśli został podany.
`serialNumber`	Numer seryjny urządzenia.
`location`	Lokalizacja, do której przypisano urządzenie.

device.deleted zawiera tylko id.

Lokalizacja

Pole	Opis
`id`	Identyfikator lokalizacji.
`name`	Nazwa lokalizacji.
`archived`	`true`, gdy lokalizacja jest zarchiwizowana; w przeciwnym razie pole jest pomijane.
`path`	Hierarchia lokalizacji od najwyższego poziomu do tej lokalizacji (włącznie), każdy element z `id` i `name`.

Jeśli lokalizacja została usunięta, wysyłane jest tylko id.

Test

Obiekt wysyłany ze zdarzeniem webhook.test.

Pole	Opis
`webhookId`	Identyfikator webhooka, dla którego wysłano test.

Przykładowe payloady

Przykłady są sformatowane dla czytelności. Ciało żądania to zwarty JSON i może zawierać sekwencje \uXXXX, np. \u002B zamiast + w przesunięciu strefy czasowej. Każdy parser JSON odczyta obie postaci tak samo.

`timeEntry.created`

Odbicie zarejestrowane na urządzeniu w lokalizacji:

{
  "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`: odbicie dodane ręcznie

Odbicie dodane w BeepClock, z komentarzem:

{
  "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"
  }
}

Typy zdarzeń​

Koperta zdarzenia​

Obiekty w data​

Odbicie​

Pracownik​

Urządzenie​

Lokalizacja​

Test​

Przykładowe payloady​

timeEntry.created​

timeEntry.created: odbicie dodane ręcznie​

timeEntry.typeChanged​

timeEntry.deleted​

employee.created​

employee.updated​

employee.archived​

employee.unarchived​

employee.deleted​

device.created​

device.updated​

device.deleted​

webhook.test​