The physical world, exposed as events.

Device operations run on physical time: hardware is sourced, configured, handed to a courier, cleared through customs, and delivered to a person. Your request returns as soon as the operation is accepted; everything after that is reported as events.

• Persist the operation identifier returned by the API, then update your record as events arrive.
• Drive product behavior — notifications, onboarding checklists, asset registers — from events rather than from timers.
• Use list endpoints for reconciliation, not as a substitute for event handling.

Representative lifecycle events. The names below illustrate the lifecycle model; the confirmed event catalog for your account is issued during onboarding and may differ by partner configuration.

Every event carries a type, a creation timestamp, and a data object holding the identifiers your application needs to correlate the event with its own records.

{
  "type": "shipment.delivered",
  "created_at": "2026-08-26T16:42:11Z",
  "data": {
    "deployment_id": "dep_78219",
    "employee_id": "emp_23981",
    "device_id": "dev_82117"
  }
}

Example payloads are illustrative. Refer to your production API specification for finalized fields and schemas.

Delivery

Events are delivered to endpoints you register with the GroWrk team. Respond quickly with a success status and process asynchronously — a slow handler looks like a failed delivery.

Retry handling

• Assume failed deliveries are retried; build your endpoint to accept the same event more than once.
• Return a success status only once the event is durably stored on your side.
• Alert on sustained delivery failures — a silent endpoint means your product's view of the physical world is drifting.

Event ordering

Do not depend on receiving events in order. Physical operations run in parallel and retries can reorder delivery. Use the event timestamp and the current state of the resource to decide whether an event is newer than what you have stored, and ignore transitions that would move a record backwards.

Duplicate handling

Treat event processing as idempotent. Key your handler on the event type plus the identifiers in the payload so replaying an event produces the same result as handling it once.

Retry windows, delivery guarantees, and replay tooling are confirmed with your team during onboarding rather than promised here.

• Serve your endpoint over HTTPS only.
• Verify that a delivery genuinely came from GroWrk before acting on it; signature verification details are provided with your endpoint configuration.
• Reject deliveries whose timestamp is far outside your tolerance window to limit replay.
• Never treat payload contents as authorization — re-check the referenced records against your own data.
• Log the event type and identifiers, not the entire payload, where payloads contain personal data.

• Register a sandbox endpoint first and drive the full lifecycle there before enabling production events.
• Exercise the unhappy paths — shipment exceptions, retrieval failures — not just the successful sequence.
• Replay stored payloads against your handler in CI so lifecycle handling is covered by tests.
• Confirm your handler is safe when the same event arrives twice and when events arrive out of order.