Data update notifications

The basic Withings API is limited to 120 requests per minute for a registered partner. In order to save requests and improve data update user experience, Withings API provides a notification system.

Notifications keep your backend informed on:

  • The availability of new data
  • Specific event occurrences
  • Specific actions performed by the end user
note

Please refer to the Enterprise Plan section if you need more requests and a better SLA.

Important information

  • In order to receive data update notifications, you might need to contact your network administrator to make sure connections from the Withings IP addresses are allowed. Consult the TXT record from https://ipblock-notify.withings.net to get the range (command: dig +short TXT ipblock-notify.withings.net). Withings will update this record at least one week prior to any change. Make sure you monitor it. Please contact us if your app is hosted on the Withings HIPAA/HDS Cloud.

  • We highly recommend that you implement the notification system that makes your system reduce the number of calls by only fetching Withings services when new data is available. This system also allows you to execute a UI refresh as soon as a notification is received.

  • 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 SLA for data update notifications, please see the Enterprise plan section

  • Notifications are sent as POST calls with parameters set in the body request as form-data parameters (not in the URL).

  • Your server has to respond with a 200 HTTP OK status in under 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 request to. This endpoint is called callbackurl and must be listed in the Callback URI field in your Withings Partner dashboard.

note

If your app is hosted on the Withings HIPAA/HDS cloud, your callback URL will be accessible from the HIPAA Partner Dashboard.

Withings will use this callbackurl and send parameter information including notification category, source and date of new data or action.

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

For instance, 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

Implementation

Refer to the Notify service documentation to implement the notification subscription.

Description of parameters

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

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

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.

  • 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 enddateMeasure - Getmeas
2user.metricsNew temperature-related data amongst meastypes:
ValueDescription
12Temperature (celsius)
71Body Temperature (celsius)
73Skin Temperature (celsius)
userid appli startdate enddateMeasure - 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 enddateMeasure - 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 enddateSleep 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 deviceidNo service to call
51user.sleepeventsNew bed out event (user gets out of bed)userid appli date deviceidNo service to call
52user.sleepeventsNew inflate done event (Withings sleep sensor initial inflation is done)userid appli date deviceidNo service to call