Fulfillment Webhooks

If Tenovi will be providing fulfillment services, after a Device has been requested, Tenovi will send a callback HTTPS POST request to a provided endpoint to indicate the fulfillment status (e.g. “Shipped” or “Connected”), tracking information, and the unique hardware_uuid for the physical device that was shipped to the patient.

Fulfillment Webhook Structure

The following data is included in each fulfillment webhook POST request:

Parameter	Description
hwi_device_id	The unique id returned when activating a HWI Device, which should be used to link shipping updates to a particular Patient or HWI Device in the Client’s software.
patient_id	The patient’s external_id, if it was provided when the device was requested (see Activating/Requesting Devices). This is the stable identifier for linking fulfillment data back to a patient; see Patient Data in Webhooks.
hardware_uuid	A unique identifier associated with the Tenovi Gateway. This is primarily useful for troubleshooting, or if a replacement Gateway is needed (Tenovi must be provided with the old ID so they can replace it with the new ID after a replacement unit is shipped out). Do NOT use this field to associate measurements with a patient, as it will change if a Gateway is replaced.
sensor_code	The sensor code of the device (see Activating/Requesting Devices for valid sensor codes)
device_name	The name of the Device that was shipped (i.e. “Tenovi Scale”, “Tenovi BPM”, “Tenovi Pulse Ox”, or “Tenovi Glucometer”). See our Device Overview page for a complete listing of available device types.
status	The fulfillment status. Values serialize as the readable labels listed in Fulfillment/Device Status Definitions, including “In Transit”, “Out for Delivery”, and “Delivery Issue”.
tracking_link	The tracking link for this device, if it has been shipped
carrier_name	The shipping carrier for this device, if available.
tracking_number	The carrier tracking number for this device, if available.
device_id	Only used for replacement devices using the Replacement API calls. The old Gateway ID or IMEI that was replaced.

Update status handling as of August 24, 2026

Your integration may now receive In Transit, Out for Delivery, and Delivery Issue in the webhook status field. Make sure your system accepts these new values.

If your workflow does not need to act on a status, accept the webhook and either store it or ignore it. Do not reject the webhook only because your system does not recognize the status.

Fulfillment/Device Status Definitions

Note

A fulfillment webhook is sent every time the status changes for a device order.

• Pending Shipment: A request for a device to be fulfilled by the client hasn’t been fulfilled yet.
• Dropship Requested: A request to dropship a device has been made but has yet to leave Tenovi warehouses.
• Shipped: A request has been shipped by the client.
• Dropshipped: A dropship request has left Tenovi warehouses.
• In Transit: The carrier is moving the shipment through its delivery network.
• Out for Delivery: The carrier expects to attempt delivery that day.
• Delivery Issue: The carrier has reported an exception or other issue with the shipment. All carrier exception types use this single status, and the webhook does not include the carrier’s reason.
• Delivered: The device has been successfully delivered to the patient’s address and is ready to be set up.
• Available for Pickup: The device has arrived at a carrier facility (e.g. FedEx OnSite, local Post Office) and is awaiting collection by the patient. See note below.
• Returned: A device has been returned to Tenovi’s warehouses.
• Connected: A device is connected and has sent measurement data.
• Replaced: A device has been replaced with a new device, see more detailed notes below.
• Unlinked: A device has been unlinked and can be re-used or repurposed.
• Client Action Required: The client needs to update a request before it can be processed if, for example, the address is invalid or it is flagged as a duplicate request.
• On Hold: A request is temporarily on hold at Tenovi (for example, if the requested device is temporarily out of stock).
• Ready to Ship: A request has passed our automated internal validation and is now ready for internal processing.

Note

Delivered will only fire when a package is dropped off at the patient’s address. It will not fire for packages held at a carrier facility — those trigger Available for Pickup instead.

If your integration performs actions on Delivered (e.g. enrolling a patient, starting a billing cycle, or sending a welcome message), those actions will not fire for packages held for pickup. We recommend updating your logic to handle both Delivered and Available for Pickup as actionable events, depending on your workflow requirements.

Webhook Frequency

A fulfillment webhook is sent for every status change. A shipment that previously generated callbacks for Shipped and Delivered may now also generate callbacks for In Transit and Out for Delivery. For a common shipment progression, this can roughly double the number of callbacks.

Do not assume that a shipment will generate a fixed number of callbacks. Integrations that rate limit processing, store an event row for every callback, deduplicate events, or calculate usage from webhook volume should account for the additional events.

Retrieving Shipment Progress

The GET hwi-devices endpoint returns current shipment progress in the nested fulfillment_request object.

Field	Description
shipping_status	The current fulfillment status. See Fulfillment/Device Status Definitions.
estimated_delivery_date	The carrier’s current estimated delivery date, if available.
in_transit_on	The date and time the shipment first entered In Transit, if available.
out_for_delivery_on	The date and time the shipment first entered Out for Delivery, if available.
shipping_status_details	A read only, nullable detail string supplied by the carrier through EasyPost.

GET Request Example

Fulfillment webhooks push status changes to your endpoint as they happen, but they do not include every available shipment detail. To retrieve more information, use the hwi_device_id from the webhook to make a GET request for that HWI Device:

GET https://api2.tenovi.com/clients/CLIENT_DOMAIN/hwi/hwi-devices/12345678-abcd-1234-abcd-1234567890ab/

The response includes the additional shipment information in the nested fulfillment_request object:

{
  "id": "12345678-abcd-1234-abcd-1234567890ab",
  "hwi_device_id": "device-001",
  "status": "Shipped",
  "connected_on": null,
  "unlinked_on": null,
  "last_measurement": null,
  "device": {
    "id": "12345678-abcd-1234-abcd-1234567890ab",
    "fulfillment_request": {
      "created": "2025-08-24T14:15:22Z",
      "shipping_status": "Out for Delivery",
      "shipping_name": "Patient One",
      "shipping_address": "123 Main Street",
      "shipping_city": "Portsmouth",
      "shipping_state": "NH",
      "shipping_zip_code": "03801",
      "shipped_on_behalf_of": "Example Health",
      "shipping_tracking_link": "https://ups.com/tracking-number",
      "ship_gateway_only": false,
      "require_signature": true,
      "shipped_on": "2025-08-24T14:15:22Z",
      "delivered_on": null,
      "estimated_delivery_date": "2025-08-27",
      "in_transit_on": "2025-08-25T09:30:00Z",
      "out_for_delivery_on": "2025-08-27T07:45:00Z",
      "shipping_status_details": "Out for delivery, expected by 8:00 PM",
      "requested_by": "care-team@example.com",
      "client_notes": "",
      "notify_emails": "care-team@example.com",
      "fulfilled": true,
      "client_will_fulfill": false,
      "flagged_by_client": false,
      "invalid_address": "",
      "duplicate_device_at_address": false
    },
    "created": "2025-08-24T14:15:22Z",
    "name": "Tenovi BPM - Wide Range",
    "hardware_uuid": "123412341234",
    "sensor_code": "10",
    "sensor_id": "",
    "device_type": "83db96ac-954e-4faa-99a8-29f767b29524",
    "shared_hardware_uuid": false,
    "model_number": "TMB-2084-A",
    "model_name": ""
  },
  "patient_id": "patient-001",
  "patient_phone_number": "123-456-7890",
  "patient": {
    "external_id": "patient-001",
    "name": "Patient One",
    "phone_number": "123-456-7890",
    "email": "patient@example.com",
    "physician": "Dr. Russell",
    "clinic_name": "Example Health",
    "care_manager": "Care Manager",
    "sms_opt_in": true
  },
  "properties": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "key": "program",
      "value": "RPM"
    }
  ]
}

The webhook payload does not include a failure reason or shipping_status_details. When a webhook reports Delivery Issue, use hwi_device_id to retrieve the HWI Device and inspect this field, or follow tracking_link for the carrier’s complete history.

The HWI Device’s top level status field remains less granular than the fulfillment request. It updates for Shipped, Delivered, and Available for Pickup, but it does not change to In Transit or Out for Delivery. For example, a device whose fulfillment request is In Transit still has a device status of Shipped.

Device status filters

?status=shipped now represents devices that have shipped but have not yet been delivered, so it may return more records than previously. Use ?status=delivery_issue to retrieve devices with a delivery issue. See Fulfillment/Device Status Definitions for the statuses represented by these filters.

Patient fulfillment text messages continue to be sent for Shipped and Delivered only. Receiving an In Transit or Out for Delivery webhook does not indicate that the patient received a text message.

Replacement Devices & Gateways

When a replacement Gateway or IMEI is shipped, the fulfillment webhook status will be “Replaced”. This indicates that a new device has been associated with one or more HWI Devices.

If you are requesting a replacement Gateway, Tenovi will automatically update the hardware_uuid of any HWI Devices linked to the same Gateway as the referenced HWI Device. Our system will send a Fulfillment Webhook with the updated Gateway ID when the replacement is shipped.

If multiple HWI Devices were linked to the original Gateway, each will generate its own “Replaced” webhook.

The fulfillment webhook payload will have the following for all replacements Tenovi ships.

• hardware_uuid: The new Gateway ID or IMEI sent as a replacement
• device_id: The old Gateway ID or IMEI that was replaced
• status: Always “Replaced” in this context

You can find more detailed information on our Replacing Devices & Gateways doc.

Example JSON Payload

{
    "hwi_device_id": "12345678-abcd-1234-abcd-1234567890ab",
    "patient_id": "12345678-1234-12345678",
    "hardware_uuid": "fed091a643ff",
    "sensor_code": "10",
    "device_name": "Tenovi BPM",
    "status": "Out for Delivery",
    "tracking_link": "https://ups.com/tracking-number",
    "carrier_name": "UPS",
    "tracking_number": "1Z999AA10123456784"
}