Skip to main content

Keep user's data up to date

In order for your services to always be up to date with your program members' data, Withings API includes a data notification system.

Important

Using other mechanisms than the Data Update Notification service in order to stay up to date with your program members' data will result in data update latencies and an increased risk of getting your requests rejected (standard Withings API applications are limited to 120 requests per minute). As this will result in a poor user experience, Withings highly encourages partners to use the Data Update Notification service.

If you think you might reach the 120 requests/minute limit even while using the Data Update Notification service or if you need a better SLA, please consider enrolling in the Enterprise Plan.

Overview

Notifications will be send to your backend when health data are created, updated, deleted or when special events happen (a list of all notification categories can be found below)

Caution
  • In order to receive data update notifications, you need to contact your network administrator to make sure connections from the Withings IP addresses are allowed. Use the addresses below to get the range of addresses to whitelist. You can use the following command line: dig +short TXT *url_found_below*. Withings will update these records at least one week prior to any change. Make sure you monitor it.
    • If you are using the Withings EU Medical Cloud / Public Cloud, please whitelist the IP addresses included in ipblock-notify.withings.net and ipblock-front.withings.net
    • If you are using Withings US Medical Cloud please whitelist the IP addresses included in ipblock-notify.us.withingsmed.net and ipblock-front.us.withingsmed.net
  • When Withings servers send your server a notification, your server needs to respond with a 200 HTTP OK status within two seconds, otherwise the notification delivery will be considered as failed.
  • Make sure your server responds both to HEAD and POST requests.

Please note that we cannot not guarantee real-time notification. Delays are typically less than two minutes, but it can be longer. For an improved data update notifications SLA, please consider enrolling in the Enterprise plan

Notification delivery failure behavior

When a data update notification fails to be delivered, Withings will retry to send it after 10s.

If during a period of 20 days, there are more than 4 consecutive failures for a specific user the subscription for this user will be removed.

How to subscribe

To implement the notification system, you must subscribe to it with an access_token. You will have to specify the endpoint you want Withings to send the notification request to. This endpoint is called callbackurl and must be listed in the Callback URI field of your application. You can go to your Developer Dashboard to edit this information. Withings will use this callbackurl and send parameter information including the notification category, source and date of new data or action.

note

You can view and edit your registered callback URLs on your Developer Dashboard

For notification categories related to user data (see table below), once your system receives a Withings notification, it can fetch new available data for the corresponding data category.

Notifications format

Notifications are sent as POST requests with parameters formatted as application/x-www-form-urlencoded.

Example

If your callback URL is:

https://www.yourdomain.net/yourpath.php&foo=bar

You will receive a POST request on this URL, and the body will contain information that specifies that new weight-related data are available for user 12345 between startdate=1530576000 and enddate=1530698753:

foo=bar
userid=12345
appli=1
startdate=1530576000
enddate=1530698753

Your system can then call the Measure - Getmeas service with the following parameters:

meastypes=1,5,6,8,76,77,88,91
category=1
startdate=1530576000
enddate=1530698753

Description of parameters

The following table describes the POST parameters that the Withings server will send to your callback URL in a notification request.

NameTypeDescription
useridintdata source
deviceidintevent trigger source
appliintdata category
startdateepochdata date
enddateepochdata date
datey-m-ddata or event date
actionstringValue amongst:
  • delete if user is deleted
  • unlink if user unlinks your app
  • update if user updates their information

Refer to the notification categories below for information about which parameters you will receive depending on the notification category you subscribe to.

Notification categories

Below is a list of notification categories to which you can subscribe. Here's an explanation of the different columns:

  • Appli: the value you must use when subscribing to the notification category.
  • Scope: permission scope you request when you obtained this user's authorization code.
  • Notification source: data or events that triggered the notification.
  • Notification params: parameters set by the Withings server in the body of the POST call sent to the callback URL to notify your server.
  • Services to call: the Health Data API services you should call to retrieve the new available data.
AppliScopeNotification triggerNotification paramsServices to call
1user.metricsNew weight-related data amongst meastypes:
ValueDescription
1Weight (kg)
5Fat Free Mass (kg)
6Fat Ratio (%)
8Fat Mass Weight (kg)
71Body Temperature (celsius)
73Skin Temperature (celsius)
76Muscle Mass (kg)
77Hydration (kg)
88Bone Mass (kg)
91Pulse Wave Velocity (m/s)
userid
appli
startdate (unix timestamp)
enddate (unix timestamp)
Measure - Getmeas
2user.metricsNew temperature-related data amongst meastypes:
ValueDescription
12Temperature (celsius)
71Body Temperature (celsius)
73Skin Temperature (celsius)
userid
appli
startdate (unix timestamp)
enddate (unix timestamp)
Measure - Getmeas
4user.metricsNew pressure related data amongst meastypes:
ValueDescription
9Diastolic Blood Pressure (mmHg)
10Systolic Blood Pressure (mmHg)
11Heart Pulse (bpm) - only for BPM and scale devices
54SP02 (%)
userid
appli
startdate (unix timestamp)
enddate (unix timestamp)
Measure - Getmeas
16users.activityNew activity-related data:
  • steps
  • distance
  • calories
  • intensity
  • workouts
userid
appli
date (YMD date)
Measure v2 - GetactivityMeasure v2 - GetintradayactivityMeasure v2 - Getworkouts
44users.activityNew sleep-related data:
  • sleep duration
  • sleep state
  • sleep state duration (light and deep, no REM)
  • sleep wakeup counts
userid
appli
startdate (unix timestamp)
enddate (unix timestamp)
Sleep v2 - GetSleep v2 - Getsummary
46user.infoNew action on user profile:
  • delete
  • unlink
  • update
userid appli actionNo service to call
50user.sleepeventsNew bed in event (user lies on bed)userid
appli
date (unix timestamp)
deviceid
No service to call
51user.sleepeventsNew bed out event (user gets out of bed)userid
appli
date (unix timestamp)
deviceid
No service to call
52user.sleepeventsNew inflate done event (Withings sleep sensor initial inflation is done)userid
appli
date (unix timestamp)
deviceid
No service to call
53n/aNo account associated: a user tried to set-up his Withings Cellular Pro device or Wthings device using the Withings Data HUB but the device is not pre-associated to a Withings account.appli macUser v2 - Activate or User v2 - Link to associate the device to a Withings account.
54user.metricsNew ECG datauserid
appli
startdate (unix timestamp)
enddate (unix timestamp)
Heart v2 - List
55user.metricsNew ECG measure failed eventuserid
appli
date (unix timestamp)
deviceid
No service to call
58user.metricsNew glucose datauserid
appli
startdate (unix timestamp)
enddate (unix timestamp)
Measure - Getmeas
Help

Login required

Please log in to your Developer Dashboard in order to file a request.

OK