Webhook (Async)

Wellhub 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 canceled but has returned to purchase a Wellhub plan and is once again eligible for the partner's services. If you do not register a Change URL, you will need to ensure that a previous user will be able to reactivate the app following the normal registration flow without any errors, otherwise, you must provide a Change URL. Multi-offer partners will receive the status of the user via the Change URL when a user returns from being canceled, does an upgrade, or does a downgrade and is eligible for more or less access to the partner app. The Change URL is ALWAYS mandatory for multi-offer partners.

Data format

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

Security

When Wellhub 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, ensure to use the secret key that you register in the portal along with your webhook endpoint. Compare the string with the header value. If they match, the message came from our servers.

The Secret key has a max char limit of 100 characters

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 with a secret of your choice 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.

Turning on my Webhooks

After registering your webhooks on the partner portal, please ensure to communicate to your Wellhub technical focal point so that we can turn on the webhooks on our end. If we do not enable the webhooks on our end too, you will not receive any events.

Cancel Events

POST - cancel

https://partner-webhook-url/cancel

Triggered whenever a user has canceled, paused or downgraded their Wellhub 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 "event_time": 1560983373378,
5 "event_id": "7e8cbb0f-9681-4d3e-8c36-2b3dd6ecbadb",
6 "event_type": "wellness-user-plan-canceled"
7}

Request Params

Headers

Responses

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

If you are a "multi-offer" partner, this webhook is triggered whenever a user has downgraded their plan to a lower-tier offer that you have or upgraded their Wellhub plan to a higher-tier offer that you have, as well as to inform you of returning users changing from status 0 to status 1, 2, 3, etc. For all other partners, this webhook will be triggered to inform you when a user has repurchased their plan and should have their premium access granted back (status 1).

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

Request Params

Headers

Responses

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

Partner plan endpoint (Sync)

This endpoint provides Wellhub's Partners with real-time access to the current user's plan status, enabling them to synchronously track user activities and engagements.

Implementation possibilities

1. Call this endpoint whenever a Wellhub user schedules or utilizes a service to verify their status in real-time
2. Schedule regular status checks by invoking this endpoint at least once a month or every two months. This can be based on the user's registration or creation date
3. Use this endpoint to perform batch verification of user statuses, this could be done in bulk or divided into manageable chunks (i.e. 50 requests per minutes)
   • Example, verify 5000 users on the 15th of each month at a rate of 50 users per minute
   • Alternatively, verify 500 users daily, starting from the 1st of the month, at a rate of 50 users per minute until all users have been checked

Attention: In the event of an excessive number of requests from the same partner, Wellhub will respond with a 429 (TOO MANY REQUESTS) status code. Please be aware that Wellhub accepts batch loads at a rate of up to 50 requests per minute.

Environments

• Production URL: https://api.wellness.gympass.com

GET /v1/partner-plans

Request

Request Example
1curl --location 'https://api.wellness.gympass.com/v1/partner-plans?gpw-id=gpw-ec5bcb09-6e4d-46c2-b978-05ad44ca41c0' \
2--header 'Content-Type: application/json' \
3--header 'Authorization: Bearer <gpw-api-key>'

Headers

Query Params

* At least one of the following query parameters is necessary for the call. If multiple parameters are provided, the precedence will be as above, where gpw-id has a higher precedence over the others.

Response

Response body schema

Schema
1{
2  "$schema": "http://json-schema.org/draft-04/schema#",
3  "type": "array",
4  "items": [
5    {
6      "type": "object",
7      "properties": {
8        "partner_plan_id": {
9          "type": "string"
10        },
11        "user": {
12          "type": "object",
13          "properties": {
14            "gpw_id": {
15              "type": "string"
16            }
17          },
18          "required": [
19            "gpw_id"
20          ]
21        }
22      },
23      "required": [
24        "partner_plan_id"
25      ]
26    }
27  ]
28}

Response Body Example

Response Payload
1[
2    {
3        "partner_plan_id": "1",
4        "user": {
5            "gpw_id": "gpw-ec5bcb09-6e4d-46c2-b978-05ad44ca41c0"
6        }
7    }
8]