Handling webhook events


Webhook handling

Beyond testing, please ensure that webhooks are processed asynchronously and a 2xx response is returned in less than 10 seconds, or requests to your server may time out and keep being retried (see Webhook Retries .

Recommendations for event handling


If the "status" field takes the value:

  • "success", then you can save the user in your DB if they don't already exist (see user_reauth below)
  • "error", then based on the value of the "reason" field, you may choose to display an appropriate message to the user

Your handler should replace all occurences of the old user_id on your server with the new one. Note that this event type is always associated with an auth event being sent, and the order of the two is not guaranteed (you should thus make sure your handler works regardless of the ordering of the two webhooks)

Your handler should delete the user record from your end.

Your handler should implement logic to ask the user to go through the authentication flow once more, or hit the Deauthenticate User endpoint and inform the user that that connection has been terminated


athlete, activity, body, daily, menstruation, nutrition, sleep

Your handler should ingest the data, storing it and processing it appropriately as per your application's needs