Introduction

What is a webhook?

A webhook is a system where one party sends events to another in a constant stream. In a Dose Health webhook, we send events regarding your Flips to you. The different types of events available are explained below.

What is a webhook not?

Webhooks differ from REST APIs in that once they’re set up, you do not need to continually poll us for updates. Instead, we will send them to you as they occur.

Webhooks also differ from websockets, which use a single long-lived connection that allows two-way communication. The Dose Health webhook includes only one-way communication from us to you, and each update is a separate HTTP request.

Who can use our webhooks?

All Dose Health partners can have webhooks set up! To partner with Dose Health, please email partners@dosehealth.com.

How many webhooks can I have?

You can have up to 5 webhooks! Keep in mind, however, that events from every one of your Flips will be sent to each of your webhooks. It will be up to you to take appropriate action per Flip.

What do our webhooks look like?

Every event in a webhook is an HTTP POST request to an endpoint that you provide us. These requests contain a few headers:

  • Content-Type: application/json
  • Authorization: Bearer YOUR_SECRET_TOKEN

YOUR_SECRET_TOKEN is a password that you provide us so that you know it’s us making requests to your endpoint.

As you may have guessed from the first header, the body of each request is a JSON object. This object has the following properties:

deviceTypestring

This property will always be the string "DOSE_FLIP".

serialNumberstring

The serial number of the Dose Flip that this event occurred for.

readingDateTimenumber

The UNIX timestamp (in seconds) for when this event occurred.

postingDateTimenumber

The UNIX timestamp (in seconds) for when this event was sent in the webhook.

valuestring

Denotes the type of event. The list of possible values is explained below.

payloadobject

An object containing the full status of the Flip. This property is only present if value === "Status".

What kinds of events are in a webhook?

There are two main categories of event types available in a Dose Health webhook.

Flip-driven

These event types are triggered by the Flips themselves. Each Flip keeps track of several state variables, and when one of them changes, it broadcasts these events to us. We in turn send these to you in our webhooks.

This category has two further sub-categories:

  • Status events

    Each of these events contains the entire state of a Flip inside the property payload.

    By storing these payloads in your own systems and comparing them to new payloads, you can see in real time when certain events occur on your Flips.

    These events are included by default in new webhooks, and can be turned on or off in the Dose Health Dashboard.

  • Legacy events

    These event types are sent out for each Flip when our systems notice certain state variables changing.

    Unlike the “Status” event type mentioned above, these event types do not include the entire state of the Flip; rather, they only include information about the particular event that occurred.

    These event types are not included by default in new webhooks, but can still be turned on or off in the Dose Health Dashboard.

Schedule-driven

These event types are scheduled to occur at the same time each day.

They are also not included by default in new webhooks, and can also be toggled on or off in the Dose Health Dashboard.

Just like the “Legacy” event types, these event types only include information about the particular event that occurred.

The “Status” Flip-driven event type

Webhook events with the value === "Status" include the entire state of the Flip inside the property payload. This property is an object, which itself has the following properties:

batteryPercentnumber

The battery level of the Flip, from 0-100.

firmwareVersionnumber

The version number of the firmware running on the Flip.

isDispensedboolean

True if the current med time has been dispensed, and false otherwise.

If isEarlyDispenseEnabled === true, then isDispensed can also be true if the next med time has been dispensed early.

If isLateDispenseEnabled === true, then isDispensed can also be true if the just-passed med time has been dispensed late.

isEarlyDispenseEnabledboolean

True if early dispense is enabled, and false otherwise. Early dispense allows a med time to be dispensed up to 8 hours before it begins.

isEarlyDispenseStartedboolean

True if “dispense early” has been pressed for the next or current med time. Stays true even after the Flip has been dispensed. This is different from isLateDispensePending.

isFlippedboolean

True if the Flip has been tipped at least 90° away from horizontal, and false otherwise.

isLateDispenseEnabledboolean

True if late dispense is enabled, and false otherwise. Late dispense allows a med time to be dispensed up to 2 hours after it ends (i.e. 4 hours after it begins).

isLateDispensePendingboolean

True if “dispense late” has been pressed for the just-passed med time, but the Flip has not been dispensed yet. False otherwise, including after the Flip has been dispensed. This is different from isEarlyDispenseStarted.

isLidOffboolean

True if the lid of the Flip is off, and false if the lid is secured.

isMedTimeboolean

True if the Flip is currently in a 2-hour med time, and false otherwise (even if early/late dispense are enabled).

isPausedboolean

True if the Flip is paused, and false otherwise. When paused, the Flip will not open or alarm for any med times.

isRefillingboolean

True if the Flip is in “refilling mode”, and false otherwise.

isRTCDeadboolean

True if the battery of the Flip’s real-time clock (which is separate from the Flip’s main internal battery) has failed and requires replacing. False otherwise.

isSettingUpboolean

True if the Flip is in “setup mode”, and false otherwise.

isTrayStuckboolean

True if the Flip’s motor is attempting to turn, but has sensed something blocking it.

medTimesArray<Object>

This property is an array of objects where each object corresponds to a med time.

medTimes[i].startnumber

The start time of a med time, in minutes since midnight, in the Flip’s local timezone (e.g. 480 corresponds to 8am, since 8 × 60 = 480).

medTimes[i].stopnumber

The end time of a med time, in minutes since midnight, in the Flip’s local timezone.

nextSlotnumber

The index of the next slot that the Flip will open to, from 0-13.

If the Flip is currently open, then this value will be identical to openSlot.

This value will increment once a med time is either dispensed or ended. For example, consider a just-refilled Flip with two med times: 8am (dispensed at 8:05am) and 6pm (missed).

  • At 7:59am, nextSlot will be 0.
  • At 8am, nextSlot will still be 0.
  • At 8:05am, nextSlot will increment to 1.
  • At 5:59pm, nextSlot will still be 1.
  • At 6pm, nextSlot will still be 1.
  • At 7:59pm, nextSlot will still be 1.
  • At 8pm, nextSlot will increment to 2.

If slotCount is 7, then odd numbers will be skipped.

nextOrCurrentMedTimenumber

The index of the next or current med time, from 0-3.

This index increments once a med time has ended. For example, consider a Flip with two med times: 8am and 6pm.

  • At 8am, nextOrCurrentMedTime will be 0.
  • At 9:59am, nextOrCurrentMedTime will still be 0.
  • At 10am, nextOrCurrentMedTime will increment to 1.
  • At 6pm, nextOrCurrentMedTime will still be 1.
  • At 7:59pm, nextOrCurrentMedTime will still be 1.
  • At 8pm, nextOrCurrentMedTime will increment and wrap back to 0.
openingModestring

This property describes how the Flip will open when a med time starts. It can take one of two values.

"auto"

When a med time starts, the Flip will immediately open to the next slot. This is the default setting.

"manual"

When a med time starts, the Flip will display a button on its screen, and will wait for this button to be pressed before opening to the next slot.

This setting is only valid when the Flip is plugged in to power. When the Flip is unplugged, it will behave according to "manual" opening mode.

openSlotnumber or null

The slot that the Flip is currently open to, from 0-13. If null, then the Flip is closed.

If slotCount is 7, then odd numbers will be skipped.

powerModestring

The method the Flip is currently using to power itself:

"battery"

The Flip is using its own internal battery for power.

"external"

The Flip is plugged in to an external power source.

scheduleModestring

This property describes how the Flip is scheduled to open. It can take one of two values.

"fixed"

The Flip has scheduled med times that are the same every day. Users can configure up to 4 med times, but 2 is the maximum recommended per Flip. This is the default setting.

"prn"

The Flip has no scheduled med times. Instead, the Flip is set to dispense pro re nata, or on an as-needed basis. Users can set a minimum delay between each dispense, ranging from 5 minutes to 120 hours.

When in this mode, the following payload properties will be null:

  • isDispensed
  • isEarlyDispenseEnabled
  • isEarlyDispenseStarted
  • isLateDispenseEnabled
  • isLateDispensePending
  • isMedTime
  • medTimes
  • nextSlot
  • nextOrCurrentMedTime
  • openingMode
  • volume
signalStrengthnumber or null

The signal strength of the Flip, from 0-100.

If null, then the Flip is not connected to signal at all.

slotCountnumber

The type of tray that the Flip is configured to use. There are two types: 7 and 14.

The default setting is 14.

timezoneOffsetnumber

The offset of the Flip’s timezone from UTC in minutes. E.g. 300 corresponds to CDT during Daylight Saving Time, and EST during the rest of the year.

volumenumber

The volume setting of the Flip, from 0-3.

  • 0 means “muted”.
  • 1 means “low volume”.
  • 2 means “medium volume”.
  • 3 means “high volume”.

Legacy Flip-driven event types

Dispensed

The Flip was flipped over during a med time (i.e. the meds were taken). Med times last for 2 (two) hours, but can be extended to last for 12 (twelve).

Missed

The Flip was not flipped over during a med time, and the Flip is now closed.

NeedsRefilled

The Flip has entered “refilling mode”. This occurs after all slots on the Flip are recorded as empty.

Refilled

The Flip has exited “refilling mode”. This occurs after the lid has been removed and put back on while in “refilling mode”.

LidRemoved

The lid was removed from the Flip (outside of “refilling mode”).

LidSecured

The lid was put back on the Flip (outside of “refilling mode”).

PluggedOut

The Flip was unplugged from power.

PluggedIn

The Flip was plugged back in to power.

TravelModeActivated

The Flip has been unplugged for 30 seconds without activity and is entering “travel mode” to conserve battery.

LowBattery

The battery on the Flip is below 20%.

MotorObstructed

The Flip has sensed that something is preventing the motor from turning.

Schedule-driven event types

In addition to the above Flip-driven event types, the following schedule-driven event types are optionally available:

Notify0Minutes

A med time has started. Again, med times last 2 (two) hours.

Notify30Minutes

30 minutes have passed in a med time, and the Flip has not been dispensed yet. There are 90 minutes remaining in the med time.

Notify60Minutes

60 minutes have passed in a med time, and the Flip has not been dispensed yet. There are 60 minutes remaining in the med time.

Notify90Minutes

90 minutes have passed in a med time, and the Flip has not been dispensed yet. There are 30 minutes remaining in the med time.

NotifyEmpty30Minutes

The Flip is in “refilling mode”, and a med time is arriving in 30 minutes.

Example JSON

Below are several example JSON objects representing the different types of events you might receive in a Dose Health webhook.

A “Status” Flip-driven event

{
  "deviceType": "DOSE_FLIP",
  "serialNumber": "123456789098765432123456",
  "postingDateTime": 1690382373,
  "readingDateTime": 1690382371,
  "value": "Status",
  "payload": {
    "batteryPercent": 94,
    "firmwareVersion": 4525,
    "isDispensed": false,
    "isEarlyDispenseEnabled": true,
    "isEarlyDispenseStarted": false,
    "isFlipped": false,
    "isLateDispenseEnabled": true,
    "isLateDispensePending": false,
    "isLidOff": true,
    "isMedTime": false,
    "isPaused": false,
    "isRefilling": false,
    "isRTCDead": false,
    "isSettingUp": false,
    "isTrayStuck": false,
    "medTimes": [{
      "start": 1260,
      "stop": 1380
    }],
    "nextSlot": 1,
    "nextOrCurrentMedTime": 0,
    "openingMode": "auto",
    "openSlot": null,
    "powerMode": "external",
    "scheduleMode": "fixed",
    "signalStrength": 100,
    "slotCount": 14,
    "timezoneOffset": 300,
    "volume": 0
  }
}

A legacy Flip-driven event

{
  "deviceType": "DOSE_FLIP",
  "serialNumber": "123456789098765432123456",
  "postingDateTime": 1690382373,
  "readingDateTime": 1690382371,
  "value": "LidRemoved"
}

A schedule-driven event

{
  "deviceType": "DOSE_FLIP",
  "serialNumber": "123456789098765432123456",
  "postingDateTime": 1690380000,
  "readingDateTime": 1690380000,
  "value": "Notify0Minutes"
}