Webhooks - Hellotracks API documentation

With webhooks you get immediate updates from Hellotracks without frequent polling. Hellotracks sends webhook callbacks to your configured endpoint when matching events occur.

Webhook Setup

You can configure API-managed webhook endpoints with /api/setwebhooks or the public REST API.

`/api` Webhook API

Use /getwebhooks to read the current configuration and /setwebhooks to update one or more endpoints.

curl -X POST https://api.hellotracks.com/api/getwebhooks \
  --header "API-Key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  -d '{ "data": {} }'

curl -X POST https://api.hellotracks.com/api/setwebhooks \
  --header "API-Key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  -d '{
    "data": {
      "alert_triggered": {
        "url": "https://example.com/hellotracks/alerts",
        "header": {
          "Authorization": "Bearer YOUR_WEBHOOK_SECRET"
        }
      }
    }
  }'

/api/setwebhooks uses these API-managed webhook keys:

job_created
job_updated
job_completed
job_archived
job_deleted
job_checked
place_checked
clock_in_out
alert_triggered

For job check-in/out webhooks, set data.job_checked.url and optionally data.job_checked.header. For place check-in/out webhooks, set data.place_checked.url and optionally data.place_checked.header. For clock-in/out webhooks, set data.clock_in_out.url and optionally data.clock_in_out.header. For alert webhooks, set data.alert_triggered.url and optionally data.alert_triggered.header. Each key accepts:

url: The HTTPS endpoint Hellotracks should call.
header: Optional object of custom HTTP headers to include with the callback.

Public REST API

No-code connectors and REST integrations can configure webhooks through /v1/webhooks.

curl https://api.hellotracks.com/v1/webhooks \
  --header "API-Key: YOUR_API_KEY"

curl -X PUT https://api.hellotracks.com/v1/webhooks \
  --header "API-Key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  -d '{
    "webhooks": {
      "alert_triggered": {
        "url": "https://example.com/hellotracks/alerts",
        "headers": {
          "Authorization": "Bearer YOUR_WEBHOOK_SECRET"
        }
      }
    }
  }'

The public REST API accepts the webhook keys listed above. For check and clock webhooks, set the matching key under webhooks, for example webhooks.job_checked.url, webhooks.place_checked.url, or webhooks.clock_in_out.url. Use headers for optional custom callback headers. Use headers in /v1/webhooks requests; /api/setwebhooks uses header.

Webhook Event Summary

Configuration	Delivered action(s)	Payload section
`job_created`	`jobcreated`	Job Webhook Payload
`job_updated`	`jobupdated`	Job Webhook Payload
`job_completed`	`jobcompleted`	Job Webhook Payload
`job_archived`	`jobarchived`	Job Webhook Payload
`job_deleted`	`jobdeleted`	Job Webhook Payload
`job_checked`	`jobcheckin`, `jobcheckout`	Job Webhook Payload
`clock_in_out`	`clockin`, `clockout`	Clock In/Out Webhook Payload
`place_checked`	`placecheckin`, `placecheckout`	Place Check Webhook Payload
`alert_triggered`	`alerttriggered`	Alert Webhook Payload

Delivery Format

Hellotracks calls your endpoint with a POST request. For standard webhook callbacks, the POST body contains form parameters:

account: The company account username.
id: The event identifier. For job events this is the job ID. For clock events this includes the member UID, timestamp, and action. For alert events this is the alert instance ID.
data: JSON string with event-specific data.
action: The delivered action.
reason: Same value as action.

POST https://<your-endpoint>

Supported delivered actions:

jobcreated: called when a job is newly created
jobupdated: called when an existing job is updated
jobcompleted: called when a job is marked as completed, either with success or failure
jobarchived: called when a job is marked as archived
jobdeleted: called when a job is deleted
jobcheckin: called when a job is checked in
jobcheckout: called when a job is checked out
clockin: called when a worker turns tracking on, which is treated as clock-in
clockout: called when a worker turns tracking off, which is treated as clock-out
placecheckin: called when a member automatically checks in at a place
placecheckout: called when a member automatically checks out from a place
alerttriggered: called when an alert configuration triggers

Job Webhook Payload

Job webhooks send the job ID as id and a compact job array as data.

account=<company_username>
id=<job_id>
data=[{<job_data>}]
action=<job_action>
reason=<job_action>

The job action is one of jobcreated, jobupdated, jobcompleted, jobarchived, jobdeleted, jobcheckin, or jobcheckout. See Job API Object for job fields.

Clock In/Out Webhook Payload

Clock in/out webhooks use the API-managed clock_in_out key. Hellotracks sends action=clockin when a worker turns tracking on and action=clockout when a worker turns tracking off.

account=<company_username>
id=<member_uid>-<timestamp_millis>-clockin
data={
  "who": {
    "uid": "<member_uid>",
    "name": "<member_name>",
    "username": "<member_username>"
  },
  "tracking": true,
  "ts": <timestamp_millis>,
  "location": {
    "lat": 37.7749,
    "lng": -122.4194
  }
}
action=clockin
reason=clockin

For clock-out events, action and reason are clockout, id ends with clockout, and data.tracking is false. Clock payload fields:

who: Member who changed tracking state.
tracking: true for tracking on / clock-in, false for tracking off / clock-out.
ts: Event timestamp in milliseconds.
location: Optional latitude/longitude object. It is omitted when Hellotracks did not receive a valid location for the tracking-state event.

Clock in/out webhooks are sent when a worker changes tracking on or off from the mobile app and that event is accepted as the worker’s current tracking state. Admin or manual timesheet changes, such as adding or correcting a clock entry in the web app, update the timesheet data but do not trigger clock in/out webhooks.

Place Check Webhook Payload

Place check webhooks send a unique check event ID as id and place/member/timestamp details as data.

account=<company_username>
id=<member_id>-<place_uid>-<timestamp_millis>
data={
  "place": { <place_data> },
  "who": {
    "uid": "<member_uid>",
    "name": "<member_name>",
    "username": "<member_username>"
  },
  "ts": <timestamp_millis>
}
action=placecheckin
reason=placecheckin

For check-out events, action and reason are placecheckout. See Place API Object for place fields.

Alert Webhook Payload

Alert webhooks use action=alerttriggered and reason=alerttriggered. The id field is the alert instance ID.

account=<company_username>
id=<alert_instance_id>
data={
  "alert": {
    "id": "<alert_instance_id>",
    "config": "<alert_config_id>",
    "companyUid": "<company_uid>",
    "title": "Late arrival",
    "description": "Notify dispatch when a worker checks in late",
    "message": "Alert: Late arrival - (Worker Name) checks in at (Customer Site) Time: 05/19/2026 09:15",
    "action": "checks_in",
    "actionCode": 1,
    "type": 1,
    "interval": 0,
    "tsCreated": 1779174900000
  },
  "member": {
    "uid": "<member_uid>",
    "username": "<member_username>",
    "name": "<member_name>"
  },
  "place": { <place_data> },
  "zone": {
    "id": 123,
    "name": "Warehouse Zone"
  },
  "checkType": "IN"
}
action=alerttriggered
reason=alerttriggered

Alert payload fields:

alert.id: Alert instance ID.
alert.config: Alert configuration ID.
alert.companyUid: Company UID.
alert.title: Alert configuration title.
alert.description: Alert configuration description.
alert.message: Human-readable alert message generated by Hellotracks.
alert.action: Alert action name.
alert.actionCode: Numeric alert action code.
alert.type: Numeric alert type.
alert.interval: Alert interval in milliseconds, if configured.
alert.tsCreated: Alert instance timestamp in milliseconds.
member: Member who triggered or violated the alert.
place: Optional place object when the alert is place-related.
zone: Optional zone object when the alert is zone-related.
checkType: Optional check direction, IN or OUT.

Alert action names:

checks_in
checks_out
checks_any
no_check_in
no_check_out
no_check_any
idle
enters_zone
leaves_zone
no_connection_to_device
enters_danger_zone
battery_low
none

​Webhook Setup

​/api Webhook API

​Public REST API

​Webhook Event Summary

​Delivery Format

​Job Webhook Payload

​Clock In/Out Webhook Payload

​Place Check Webhook Payload

​Alert Webhook Payload

Webhook Setup

`/api` Webhook API

Public REST API

Webhook Event Summary

Delivery Format

Job Webhook Payload

Clock In/Out Webhook Payload

Place Check Webhook Payload

Alert Webhook Payload