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.

Name	Type	Description
userid	int	data source
deviceid	string	event trigger source
appli	int	data category
startdate	epoch	data date
enddate	epoch	data date
date	y-m-d	data or event date
action	string	Value 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.

Appli	Scope	Notification trigger	Notification params	Services to call
1	user.metrics	New weight-related data amongst meastypes: Value Description 1 Weight (kg) 5 Fat Free Mass (kg) 6 Fat Ratio (%) 8 Fat Mass Weight (kg) 71 Body Temperature (celsius) 73 Skin Temperature (celsius) 76 Muscle Mass (kg) 77 Hydration (kg) 88 Bone Mass (kg) 91 Pulse Wave Velocity (m/s)	userid appli startdate (unix timestamp) enddate (unix timestamp)	Measure - Getmeas
2	user.metrics	New temperature-related data amongst meastypes: Value Description 12 Temperature (celsius) 71 Body Temperature (celsius) 73 Skin Temperature (celsius)	userid appli startdate (unix timestamp) enddate (unix timestamp)	Measure - Getmeas
4	user.metrics	New pressure related data amongst meastypes: Value Description 9 Diastolic Blood Pressure (mmHg) 10 Systolic Blood Pressure (mmHg) 11 Heart Pulse (bpm) - only for BPM and scale devices 54 SP02 (%)	userid appli startdate (unix timestamp) enddate (unix timestamp)	Measure - Getmeas
16	users.activity	New activity-related data: steps distance calories intensity workouts	userid appli date (YMD date)	Measure v2 - GetactivityMeasure v2 - GetintradayactivityMeasure v2 - Getworkouts
44	users.activity	New 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
46	user.info	New action on user profile: delete unlink update	userid appli action	No service to call
50	user.sleepevents	New bed in event (user lies on bed)	userid appli date (unix timestamp) deviceid	No service to call
51	user.sleepevents	New bed out event (user gets out of bed)	userid appli date (unix timestamp) deviceid	No service to call
52	user.sleepevents	New inflate done event (Withings sleep sensor initial inflation is done)	userid appli date (unix timestamp) deviceid	No service to call
53	n/a	No 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 mac	User v2 - Activate or User v2 - Link to associate the device to a Withings account.
54	user.metrics	New ECG data	userid appli startdate (unix timestamp) enddate (unix timestamp)	Heart v2 - List
55	user.metrics	New ECG measure failed event	userid appli date (unix timestamp) deviceid	No service to call
58	user.metrics	New glucose data	userid appli startdate (unix timestamp) enddate (unix timestamp)	Measure - Getmeas