Webhooks and Outputs

info

Direction of Travel has now been included in the response, represented as an angle in degrees ranging from 0 to 360 on a Unit Circle.
Useful for cases such as detecting whether people are entering or exiting a gate.

New in version 1.4.0.

CSV

PeopleTracker output is saved in a CSV file. You can use Notepad++ to get "live" updates in the CSV output file. Here is a sample CSV output:

timestamp,track_id,score,direction,file,box
2021-10-27 06:20:43.970337+00:00,1,0.895,82,/camera-1_screenshots/23-07-05/05-36-00.595948.jpg,"{'xmin': 619, 'ymin': 429, 'xmax': 646, 'ymax': 488}"
2021-10-27 06:20:45.269216+00:00,2,0.776,291,/camera-1_screenshots/23-07-05/06-10-35.722032.jpg,"{'xmin': 335, 'ymin': 114, 'xmax': 367, 'ymax': 167}"

JSON Lines

You may also output JSON Lines. Here is a sample JSONLines output:

{"camera_id": "camera-1", "filename": "08-59-54.183408.jpg", "timestamp": "2023-07-05T08:59:54.183408Z", "timestamp_local": "2023-07-05T08:59:54.183408+00:00", "timestamp_camera": "2023-07-05T08:59:54.183408+00:00", "results": [{"box": {"xmin": 677, "ymin": 259, "xmax": 1213, "ymax": 932}, "type": "person", "score": 0.861, "track_id": 1, "direction": 358}]}
{"camera_id": "camera-1", "filename": "09-21-19.176125.jpg", "timestamp": "2023-07-05T09:21:19.176125Z", "timestamp_local": "2023-07-05T09:21:19.176125+00:00", "timestamp_camera": "2023-07-05T09:21:19.176125+00:00", "results": [{"box": {"xmin": 705, "ymin": 334, "xmax": 1156, "ymax": 945}, "type": "person", "score": 0.911, "track_id": 2, "direction": 131}]}

Webhooks

Person Detection Event

PeopleTracker On-Premises uses webhooks to send notifications when a person is detected in the video stream. If there are multiple persons, PeopleTracker will send a separate request for each one.

Example webhook JSON data:

The webhook data uses the timestamp set at frame arrival time as measured by PeopleTracker.
The response contains both the UTC timestamp and the local timestamp, reflecting the timezone configured in the PeopleTracker configuration.

New in version 1.5.0

Example Payload

{
  "hook": {
    "target": "https://webhook.site/12345",
    "filename": "09-21-49.730709.jpg",
    "id": "camera-1",
    "event": "people_detected"
  },
  "data": {
    "results": [
      {
        "box": {
          "xmin": 282,
          "ymin": 39,
          "xmax": 305,
          "ymax": 103
        },
        "type": "person",
        "score": 0.9957417249679565,
        "track_id": "a1b2c3d4-1-0",
        "direction": 95
      }
    ],
    "timestamp": "2023-11-15T09:21:49.730709Z",
    "timestamp_local": "2023-11-15T09:21:49.730709+00:00",
    "timestamp_camera": null,
    "filename": "09-21-49.730709.jpg",
    "version": 1,
    "camera_id": "camera-1"
  }
}

hook fields

Field	Type	Description
`hook.target`	`string`	Destination URL for this webhook
`hook.filename`	`string`	Filename of the captured image
`hook.id`	`string`	Camera ID that triggered the event
`hook.event`	`string`	Event type: `people_detected` or `dwell_time`

data fields

Field	Type	Description
`data.results`	`array`	List of detected persons (see result item fields below)
`data.timestamp`	`string`	UTC timestamp of detection (ISO 8601)
`data.timestamp_local`	`string`	Local timestamp reflecting the configured timezone (ISO 8601)
`data.timestamp_camera`	`string\|null`	Timestamp from camera source, if available
`data.filename`	`string`	Filename of the captured image
`data.version`	`integer`	Webhook schema version
`data.camera_id`	`string`	Camera identifier

Result item fields (each entry in data.results)

Field	Type	Description
`box.xmin`	`integer`	Left edge of bounding box (pixels)
`box.ymin`	`integer`	Top edge of bounding box (pixels)
`box.xmax`	`integer`	Right edge of bounding box (pixels)
`box.ymax`	`integer`	Bottom edge of bounding box (pixels)
`type`	`string`	Detected object type (always `"person"`)
`score`	`float`	Confidence score (0.0–1.0)
`track_id`	`string`	Unique identifier for the tracked person
`direction`	`float`	Direction of travel in degrees (0–360, Unit Circle)

Dwell Time

When dwell_time is turned on, a second POST request is sent later to the same url with no images attached. This event is sent when a tracked person leaves the field of view (after max_dwell_delay seconds).

Example Payload

{
  "hook": {
    "target": "https://webhook.site/12345",
    "id": "camera-1",
    "event": "dwell_time"
  },
  "data": {
    "results": [
      {
        "dwell_time": 4.0,
        "first_seen": "2023-11-15T09:20:13.654321+00:00",
        "last_seen": "2023-11-15T09:23:56.123456+00:00",
        "track_id": "a1b2c3d4-1-0",
        "trajectory": [ // list of historical positions or null
          {
            "position_sec": 0.07,
            "person": {
              "type": "person",
              "dscore": 0.962,
              "box": {"xmin": 686, "ymin": 449, "xmax": 721, "ymax": 552}
            },
            "timestamp": "2023-11-15T09:20:13.654321Z",
            "timestamp_local": "2023-11-15T09:20:13.654321+00:00",
            "timestamp_camera": null
          },
          ...
        ]
      }
    ],
    "timestamp": "2023-11-15T09:21:49.730709Z",
    "timestamp_local": "2023-11-15T09:21:49.730709+00:00",
    "timestamp_camera": null,
    "camera_id": "camera-1"
  }
}

Dwell time result item fields (each entry in data.results)

Field	Type	Description
`dwell_time`	`float`	Time in seconds the person was visible in the monitored area
`first_seen`	`string`	Timestamp when the person first appeared (ISO 8601)
`last_seen`	`string`	Timestamp when the person was last seen (ISO 8601)
`track_id`	`string`	Unique identifier for the tracked person
`trajectory`	`array\|null`	List of historical positions; `null` when trajectory is disabled

Trajectory entry fields (each entry in trajectory)

Field	Type	Description
`position_sec`	`float`	Time offset in seconds from `first_seen`
`person.type`	`string`	Detected object type (always `"person"`)
`person.dscore`	`float`	Detection confidence score (0.0–1.0)
`person.box`	`object`	Bounding box with `xmin`, `ymin`, `xmax`, `ymax` (pixels)
`timestamp`	`string`	UTC timestamp for this trajectory point (ISO 8601)
`timestamp_local`	`string`	Local timestamp for this trajectory point (ISO 8601)
`timestamp_camera`	`string\|null`	Camera source timestamp, if available

Video Clip

When webhook video is turned on, another POST request is sent later to the same URL with a video file attached in a video field (if video = file is set) and a different json field:

{
  "hook": {
    "target": "https://webhook.site/12345",
    "id": "camera-1",
    "event": "video_file",
    "video_filename": "camera-1_videos/23-11-15/09-21-49.730709.mp4"
  },
  "data": {
    "results": [
      {
        "track_id": "a1b2c3d4-1-0",
        "user_data": ""
      }
    ],
    "timestamp": "2023-11-15T09:21:49.730709Z",
    "timestamp_local": "2023-11-15T09:21:49.730709+00:00",
    "timestamp_camera": null,
    "url": "RESERVED",
    "video_filename": "camera-1_videos/23-11-15/09-21-49.730709.mp4",
    "camera_id": "camera-1"
  }
}

CSV​

JSON Lines​

Webhooks​

Person Detection Event​

Example Payload​

Dwell Time​

Example Payload​

Video Clip​

CSV

JSON Lines

Webhooks

Person Detection Event

Example Payload

Dwell Time

Example Payload

Video Clip