Subscriber Verification - GET vs POST

[Jeff_New_Ocean]

I am a little confused about the verification of subscriber endpoints.

In the documentation, "Verifying a Subscriber" section, it states the verification sends a GET request:

For example, the following should result in a 204:

GET https://yourapp.com/fitbit/webhook?verify=correctVerificationCode

And the following should result in a 404:

GET https://yourapp.com/fitbit/webhook?verify=incorrectVerificationCode

However, in the "Receiving Update Notifications" section, it describes the notification as a POST:

Notification Format

An update notification request to your endpoint is defined as follows:

HTTP Method	POST
Content-Type	application/json or multipart/form-data
Parameter/part name	updates
Parameter/part Content-Type	text/xml or text/javascript

Questions:

1. Is it true that the verification requests are GET requests, but the actual notifications are POST requests? This implies that your verification isn't verifying the same endpoint that is used for the subscription notifications.
   1. Given this, do I need to handle verification requests on the POST as well?
2. Are verification requests sent again periodically after the initial verification?
3. How can I re-verify my endpoint from the applications page?
4. Right now I have my GET endpoint set up to return a 204-NO CONTENT, which is correct for a GET response with no content body. However, my POST endpoint for the same path is returning a 201-CREATED, as one would expect from a successful POST response. In the documentation it says this will cause the subscriber endpoint to be disabled, but that doesn't seem to be the case. Is that because the verification is only done on my GET endpoint, which is still returning a 204?

Thanks for the clarifications.

[JohnFitbit · Accepted solution]

Hi @Jeff_New_Ocean,

Thanks for your feedback. This was really well written and will help drive some improvements to the Subscriptions API. The challenges for verifying a subscriber URL have already been acknowledged by our team. 

In the meantime, here are the answers to your questions:

1. Is it true that the verification requests are GET requests, but the actual notifications are POST requests? This implies that your verification isn't verifying the same endpoint that is used for the subscription notifications.
   1. Given this, do I need to handle verification requests on the POST as well?
2. Are verification requests sent again periodically after the initial verification?
3. How can I re-verify my endpoint from the applications page?
4. Right now I have my GET endpoint set up to return a 204-NO CONTENT, which is correct for a GET response with no content body. However, my POST endpoint for the same path is returning a 201-CREATED, as one would expect from a successful POST response. In the documentation it says this will cause the subscriber endpoint to be disabled, but that doesn't seem to be the case. Is that because the verification is only done on my GET endpoint, which is still returning a 204?

---

1. Yes, when a subscriber is added, Fitbit sends 2 GET requests to the subscriber endpoint, each with a "verify" query string parameter. One request has the subscriber verification code as the "verify" query string parameter value and expects the subscriber to respond with a 204. Another request has an intentionally invalid verification code and expects the subscriber to respond with a 404. The notifications use a POST request as it "posting" updates to your application. Once your subscriber has already been verified, no additional verification is needed.
2. No, the Subscriptions API doesn’t do any additional verification after your subscriber URL has been verified. However, if your application is unavailable when Fitbit attempts to send a notification, or your application is not responding within 5 seconds to a notification request, your subscriber will be disabled.
3. The only way to re-verify your endpoint from the applications page is to go into your application settings and delete your endpoint url. When you add it back, you’ll be prompted to go through the verification process again.
4. Our docs state that endpoints should respond to notifications with 204 -- i.e. to both the POST and the correct verification GET. https://dev.fitbit.com/build/reference/web-api/subscriptions/#notification-format

I hope this helps. Let me know if you have any additional questions.

[Jeff_New_Ocean]

Thanks JohnFitbit for the clarifications!

Sorry for the delay, I was out for a couple weeks.

Also, I wanted to let you know that while my POST subscription endpoint was returning a 201 (instead of the prescribed 204), it didn't seem to cause an issue, other than it wasn't logged as green. I switched it back to return 204 on success so that it meets the requirement though.