Skip to main content

Notification Overview

To ensure your services remain consistently updated with the latest data from your program members, the Withings API provides a Webhook / Data Notification System.

Relying solely on manual polling or other CRON-like mechanisms to fetch data may lead to significant delays and an increased risk of request rejections. The standard Withings API enforces a 120 requests-per-minute limit for all applications (see API plan details).

The Data Notification System provides real-time data updates, reducing unnecessary API calls and ensuring your services stay efficient and responsive.

If your use case demands a higher request rate or you require stricter Service Level Agreements (SLAs), consider upgrading to the Enterprise Plan, which offers enhanced API capabilities.

Notification System Overview

Notifications are sent to your backend when health data are created, updated, deleted, or when special events occur.
A list of all notification categories can be found in the Notification Content page.

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

Retry Mechanism

Our notification system implements the following retry mechanism:

Retry Attempts:

  • Each webhook notification will be attempted up to 10 times total
  • We perform 2 HTTP attempts per retry cycle
  • There are 5 retry cycles with incremental delays

Retry Schedule:

  1. Initial attempt: immediate (2 HTTP tries)
  2. 1st retry: after 10 seconds (2 HTTP tries)
  3. 2nd retry: after 1 minute + random (1-10 minutes) (2 HTTP tries)
  4. 3rd retry: after 1 hour + random (2-20 minutes) (2 HTTP tries)
  5. 4th retry: after 4 hours + random (3-30 minutes) (2 HTTP tries)

Success Criteria:

  • Your webhook endpoint should respond with an HTTP status code < 400 (ideally 2xx) to indicate successful receipt
  • Any response with status code >= 400 will be considered a failure and trigger a retry

If all attempts fail:

  • A warning email is sent to the organization's contact email for each of the first 4 consecutive failures
  • When a failure occurs and remains unresolved for 20 days or longer, the system automatically cancels the subscription and sends a notification to the organization's contact email