> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.hellotracks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Hellotracks provides webhooks for job, clock, place/check, and alert events with custom callbacks.

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.

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

```bash theme={null}
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`.

```bash theme={null}
curl https://api.hellotracks.com/v1/webhooks \
  --header "API-Key: YOUR_API_KEY"
```

```bash theme={null}
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-webhook-payload)                  |
| `job_updated`     | `jobupdated`                    | [Job Webhook Payload](#job-webhook-payload)                  |
| `job_completed`   | `jobcompleted`                  | [Job Webhook Payload](#job-webhook-payload)                  |
| `job_archived`    | `jobarchived`                   | [Job Webhook Payload](#job-webhook-payload)                  |
| `job_deleted`     | `jobdeleted`                    | [Job Webhook Payload](#job-webhook-payload)                  |
| `job_checked`     | `jobcheckin`, `jobcheckout`     | [Job Webhook Payload](#job-webhook-payload)                  |
| `clock_in_out`    | `clockin`, `clockout`           | [Clock In/Out Webhook Payload](#clock-inout-webhook-payload) |
| `place_checked`   | `placecheckin`, `placecheckout` | [Place Check Webhook Payload](#place-check-webhook-payload)  |
| `alert_triggered` | `alerttriggered`                | [Alert Webhook Payload](#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`.

```http theme={null}
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`.

```shell theme={null}
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](/api-reference/job-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.

```shell theme={null}
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.

<Note>
  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.
</Note>

## Place Check Webhook Payload

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

```shell theme={null}
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](/api-reference/place-object) for place fields.

## Alert Webhook Payload

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

```shell theme={null}
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`