User Status Webhooks

Gympass webhooks will proactively notify you whenever a user changes their status (cancel/upgrade/downgrade). It is mandatory to provide two URLs, one for cancel requests and one for change requests. The notification is an HTTP POST request to your registered URLs.

This document describes the mechanism to receive the user status update. You will be able to find below both the events that are triggered along with the data they send, and the API resources available for the webhooks.

General Information

Note: Both a cancel URL and change URL are required for all partners. Single offer partners will receive the status of a user who previously cancelled but has returned to purchase a Gympass plan and is once again eligible for the partner's services. Multi-offer partners will receive the status of the user via the change URL when a user returns from being cancelled, does an upgrade, or does a downgrade downgrade and is eligible for more or less access to the partner app.

Data format

Every API resource and push event uses JSON as its standard data format.

Security

When Gympass sends an event notification to a registered webhook, we include a signature header so you know the request was sent from our servers. The header name is X-Gympass-Signature. We strongly recommend that you verify this signature when you receive a request at your webhook endpoint.

To validate the webhook signature, you must encode the request body using an HMAC-SHA-1 library in your coding language of choice. When you do this, use the secret key that was previously registered in the Gympass system along with the webhook endpoint. Compare the string with the header value. If they match, the message came from our servers.

Retry

The response time is 1s. After that, if we have no response, we will retry for a maximum of 10 times at different intervals after the first missed response.

How to Register my Webhooks

You must register both the cancel and change webhooks by logging into the partner portal. You will see the option to "Test integration" where you can practice making a request with test information to your registered URL to ensure you are receiving the call safely and securely. Ensure to "enable" each webhook once you have entered both the URLs and a "secret", and please alert us too as we will need to enable the webhook on our end as well.

text

Cancel Events

POST - cancel

https://partner-webhook-url/cancel

Triggered whenever a user has cancelled, paused or downgraded their Gympass plan to one that no longer includes your offer.

Request example
1{
2 "user_id": "gpw-5vs3bf0a-3add-468d-85ff-a358a1befe9a",
3 "plan_id": "0",
4 "timestamp": 1560983373378,
5 "event_id": "7e8cbb0f-9681-4d3e-8c36-2b3dd6ecbadb",
6 "event_type": "wellness-user-plan-canceled"
7}

Request Params

NameTypeDescription
user_idStringexample: gpw-5vs3bf0a-3add-468d-85ff-a358a1befe9a
plan_idStringexample: 0 Plan ID or status to cancel: "0" - Cancelled / Paused, "plan_id" - Other value representing the plan

Headers

FieldDescription
Content-Typeapplication/json
X-Gympass-Signature0xfbdb1d1b18aa6c08324b7d64b71fb76370690e1d

Responses

CodeDescription
2XXStatus successfully received
404User not found (user not part of your database) - Note: this error will not trigger any retry policy
429Too many requests
5XXError receiving the user status

Note: Any status different from 2XX layer and 4XX (except for status 429) will be considered as error and will trigger the retry policy.

Change Events

POST - change

https://partner-webhook-url/change

Triggered whenever a user has downgraded their plan to a lower-tier offer that you have, or upgraded their Gympass plan to a higher tier offer that you have.

Request example
1{
2 "user_id": "gpw-5vs3bf0a-3add-468d-85ff-a358a1befe9a",
3 "plan_id": "2",
4 "timestamp": 1560983373378,
5 "event_id": "7e8cbb0f-9681-4d3e-8c36-2b3dd6ecbadb",
6 "event_type": "wellness-user-plan-changed"
7}

Request Params

NameTypeDescription
user_idStringexample: gpw-5vs3bf0a-3add-468d-85ff-a358a1befe9a
plan_idStringexample: 1 Plan ID or status to update the current user offer subscription: "1" - Lower tier plan, "2" - Upper tier plan, "plan_id" - Other value representing the plan

Headers

FieldDescription
Content-Typeapplication/json
X-Gympass-Signature0xfbdb1d1b18aa6c08324b7d64b71fb76370690e1d

Responses

CodeDescription
2XXStatus successfully received
404User not found (user not part of your database) - Note: this error will not trigger any retry policy
429Too many requests
5XXError receiving the user status

Note: Any status different from 2XX layer and 4XX (except for status 429) will be considered as error and will trigger the retry policy.