Skip to main content

Notifications overview

Receive real-time updates when your users record new health data — no polling required. Withings POSTs to your callback URL the moment new measurements arrive, then your handler fetches the data via the Data API.

Why webhooks

The standard Withings API enforces a 120 requests-per-minute limit across your application (see API plan details). Polling for fresh data hits this ceiling quickly and adds latency you can't tune.

The notification system inverts the flow: Withings tells your backend exactly when new data is ready, so you fetch only what you need, exactly when it matters.

If your use case demands a higher request rate or stricter SLA guarantees, the Enterprise plan unlocks higher limits and dedicated support.

How it works

  1. 1

    User measures

    A user takes a measurement on their Withings device.

  2. 2

    Withings detects

    Our servers identify new data for the relevant appli category.

  3. 3

    Webhook POST

    Withings sends an application/x-www-form-urlencoded POST to your callback URL.

  4. 4

    Your handler responds

    Your endpoint returns HTTP 2xx within a few seconds.

  5. 5

    You fetch the data

    See the data fetch example→

Reliability

Two layers of safety so a hiccup in your endpoint doesn't cost you data.

Per notification — 5 retry cycles over ~5 hours

If your endpoint doesn't return HTTP < 400, Withings retries the same notification on this schedule:

  1. T+0Initial
  2. +10 sRetry 1
  3. +1 minRetry 2
  4. +1 hRetry 3
  5. +4 hRetry 4

Each cycle does 2 HTTP attempts (10 attempts total). Later retries use random jitter to spread load.

Per subscription — failure escalation

When notifications keep failing despite the retries above, your subscription escalates:

  • 4 failed notifications in a rowA warning email is sent for each (max 4 emails).
  • 20 days of unresolved failuresSubscription is auto-cancelled, with a final notice email.

Missed notifications are not redelivered. Once your endpoint is back up, backfill via the Data API using lastupdate.

Real-time, but not guaranteed

Typical delivery delay is under 2 minutes, but it can occasionally be longer.

Withings does not commit to a real-time SLA on the standard plan.

Need stricter guarantees? See the Enterprise plan.

Securing notifications

We recommend hardening your callback endpoint with two complementary checks — one at the network layer, one at the application layer.

Allowlist Withings IPs

Restrict your endpoint to traffic originating from Withings. The current IP ranges are published as DNS TXT records, queryable with dig:

  • EU (default cloud)dig +short TXT ipblock-notify.withings.net
  • US Medical Clouddig +short TXT ipblock-notify.us.withingsmed.net

Withings updates these records at least one week before any change — monitor them so your allowlist stays in sync.

Verify a shared secret

When you set the callback URL on your subscription, append a query parameter only you and Withings know. Withings POSTs to this exact URL, so the parameter is delivered with every notification:

https://api.example.com/withings?token=<random-secret>

Your handler reads token from the incoming request and rejects any value that doesn't match the secret you configured. Combine this with the IP allowlist for defense in depth.