Data update notifications

In order for you services to always be up to date with the latest user data updates, Withings API includes a data notification system.

Important

Using other mecanisms than the Data Update Notification service in order to stay up to date with users 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:

  • New data is available
  • Specific events occurrence
  • Specific actions are performed by the end user

Important information

  • 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 adresses below to get the range of adresses to whitelist. You can use the following command line: dig +short TXT *url_found_below*. Withings will update thes records at least one week prior to any change. Make sure you monitor it.
  • 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 to the Enterprise plan section
  • Notifications are sent as POST calls with parameters set in the body request as form-data parameters. Parameters are therefore not passed in the URL.
  • Your server has to respond with a 200 HTTP OK status within two seconds, otherwise the notification subscription will be considered a failure. After four consecutive failures, the notification subscription is 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. 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.

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.

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

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

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 must request from the user at authorisation flow (refer to OAuth 2.0 application flow).
  • Notification source: data or events that trigger 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 Data API services you should call to retrieve new available data once you receive a notification request.
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
enddate
Measure - Getmeas
2user.metricsNew temperature-related data amongst meastypes:
ValueDescription
12Temperature (celsius)
71Body Temperature (celsius)
73Skin Temperature (celsius)
userid
appli
startdate
enddate
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
enddate
Measure - Getmeas
16users.activityNew activity-related data:
  • steps
  • distance
  • calories
  • intensity
  • workouts
userid appli dateMeasure 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
enddate
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
deviceid
No service to call
51user.sleepeventsNew bed out event (user gets out of bed)userid
appli
date
deviceid
No service to call
52user.sleepeventsNew inflate done event (Withings sleep sensor initial inflation is done)userid
appli
date
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
enddate
Heart v2 - List
55user.metricsNew ECG measure failed eventuserid
appli
date
deviceid
No service to call