Skip to main content
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 webhook keys:
  • job_created
  • job_updated
  • job_completed
  • job_archived
  • job_deleted
  • alert_triggered
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 alert webhooks, set webhooks.alert_triggered.url and optionally webhooks.alert_triggered.headers. Use headers in /v1/webhooks requests; /api/setwebhooks uses header.
Job check-in/out and place check-in/out callbacks are delivered by Hellotracks when enabled for your account. Contact api@hellotracks.com if you need help enabling a webhook that is not listed in /getwebhooks or /v1/webhooks.

​
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 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
  • 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.

​
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
  • none