Event reference

Every webhook request carries one event in a common envelope. This page lists the event types, the envelope fields, the objects sent in data and an example payload for every event.

API version

Payload API version: 2026-10, sent in the apiVersion field. New fields can be added without changing the version, so ignore fields you do not know.

Event types

Event types have the form resource.action, with the action in camelCase. When you create or edit a webhook, you select which event types it receives.

Event type	Label in BeepClock	Sent when
timeEntry.created	Entry recorded	A time entry is recorded: on a device, added manually, added automatically (automatic exit) or added when a missing entry is fixed.
timeEntry.typeChanged	Entry type changed	The type of an existing entry is changed.
timeEntry.deleted	Entry deleted	An entry is deleted.
employee.created	Employee added	An employee is added in BeepClock or imported from a device.
employee.updated	Employee details changed	The first name, last name, employee number or position changes.
employee.archived	Employee archived	An employee is archived.
employee.unarchived	Employee restored	An archived employee is restored.
employee.deleted	Employee deleted	An employee is deleted.
device.created	Device added	A device is added to the account.
device.updated	Device details changed	A device is renamed, its description changes or it is assigned to a location.
device.deleted	Device deleted	A device is deleted.
webhook.test	—	A test event sent with Send test event. It cannot be selected and is always available.

Several quick changes to the same object can be combined into one delivery. Repeated employee.updated, device.updated or timeEntry.typeChanged events processed together produce a single delivery, and an update processed together with the object's created event produces only the created delivery, already showing the updated data.

Envelope

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

Field	Description
id	Delivery identifier, equal to the X-BeepClock-Delivery header. Use it to detect duplicates.
event	Event type, equal to the X-BeepClock-Event header.
occurredAt	When the source event happened, in UTC (ISO 8601 with the Z suffix).
tenant	Identifier of the BeepClock account.
apiVersion	Version of the payload contract, 2026-10.
data	The object the event is about. Its fields depend on the resource and are described below.

Your receiver must tolerate these serialisation rules:

• field names and enum values are camelCase;
• fields without a value are omitted, so a missing field means null;
• if the object no longer exists when the delivery is prepared, for example a deleted employee or device, data contains only id;
• data describes the object as it was when BeepClock prepared the delivery, usually within seconds of the event;
• the body is compact JSON, and some characters, such as + or non-ASCII letters, may be sent as \uXXXX escapes. Read the body with a JSON parser, and verify the signature on the raw bytes.

Objects in data

Time entry

Sent with timeEntry.* events.

Field	Description
id	Identifier of the time entry.
employee	The employee: id (omitted when the employee number is not known in BeepClock), numericId (employee number on the device), firstName, lastName.
eventType	Entry type: in, out, dutyOn, dutyOff, overtimeOn, overtimeOff, goOutOn, goOutOff.
direction	in for in, dutyOn, overtimeOn and goOutOff; out for out, dutyOff, overtimeOff and goOutOn.
source	device (recorded on a device), manual (added in BeepClock) or automatic (added by BeepClock, for example an automatic exit).
time	Time of the entry in the entry's time zone, ISO 8601 with offset.
timeZone	IANA time zone of the entry, for example Europe/Warsaw.
device	Device that recorded the entry: id, name. Only for device entries.
location	Location where the entry was recorded. Only for device entries recorded at a location.
previousEntryId	The employee's previous entry that this entry follows, when there is one.
comment	Comment of a manual entry.
deletedAt	When the entry was deleted. Only in timeEntry.deleted.
deletionComment	Reason given when the entry was deleted. Only in timeEntry.deleted.

timeEntry.typeChanged carries the entry with its new eventType and direction. timeEntry.deleted carries the entry as it was, plus deletedAt and deletionComment.

Employee

Sent with employee.* events.

Field	Description
id	Identifier of the employee.
numericId	Employee number used on devices.
firstName, lastName	Name.
position	Position, when set.
archived	true if the employee is archived, otherwise false.
archivedAt	When the employee was archived.

employee.deleted contains only id.

Device

Sent with device.* events.

Field	Description
id	Identifier of the device.
name	Device name.
description	Description, when set.
serialNumber	Serial number of the device.
location	Location the device is assigned to.

device.deleted contains only id.

Location

Field	Description
id	Identifier of the location.
name	Location name.
archived	true when the location is archived; omitted otherwise.
path	The location hierarchy from the top level down to this location (inclusive), each item with id and name.

If the location has been deleted, only id is sent.

Test

Sent with webhook.test.

Field	Description
webhookId	Identifier of the webhook the test was sent for.

Payload examples

The examples are formatted for readability. The request body is compact JSON and can contain \uXXXX escapes, for example \u002B for + in a time zone offset. Any JSON parser reads both forms the same way.

timeEntry.created

An entry recorded on a device at a location:

{
  "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: manual entry

An entry added in BeepClock, with a comment:

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