How to use and set up Webhooks? – PerfectGym

Introduction

Webhook is an internet URL called for the Events occurring in the system. Using Webhooks and Perfect Gym API, makes it possible to integrate with almost any solution, system or device. The Event occurs when something within the PG system either happens or changes, i.e. a class is booked, user profile modified, or card scanned.

Webhook URL typically points to your system, or some integrations aggregator service like eg. IFTTT, Zapier. Microsoft Flow. etc. It allows to easily create integration between different systems or to trigger some actions elsewhere.

Webhooks are called just after the subscribed Event occurs in the system. The delay is no more than a few seconds.

In the PGM, you can set up numerous Webhooks. Each Webhook can be subscribed to selected Events in the system so that it is called only when these particular Events occur.

Mind that there are some limitations in use for the Webhooks. For more information, contact the Perfect Gym Sales Representative.

Why Webhooks?

Webhooks are complementary features to API. They are used especially when you create some kind of integration.

Suppose you need to react to some property change on Contract, User Profile, or any other business object in the PGM system.

Using only API, you must do polling - query API regularly to find if something has changed. It is inefficient. The better way is to have machines do the work!

To do so, subscribe to a Webhook Event. Your system will be called by the PGM as soon as a given business object has been changed.
If there are no business object attributes, you need in the Webhook Event payload. Then, you can use API to get the data desired of the given business object.

What kind of Events are available?

We have been adding new Webhook Events to the system. Please, examine the available Webhook events list in the PGM.
There, you will also find examples of event payloads. Currently, you can choose from bellow events:

ClassesBooked - The booking for classes has been made (from any app: PGM, Client Portal, POSweb, Mobile app).
ClassesBookedOnStandbyList - The booking for classes has been made but the user stays on a standby list (from any app: PGM, Client Portal, POSweb, Mobile app).
ClassesBookingCancelled - The booking for classes has been cancelled (from any app: PGM, Client Portal, POSweb, Mobile app).
ClassesBookingPromotedFromStandbyList - The user has been moved from the standby list to the main class list (check previous webhooks).
ContractPaymentDone - The payments for any contract transaction has been made.
ContractCreated - The contract has been added to the system (could be for a new member or for the old one).
PersonalTrainingBooked - The booking for the Personal Training session has been made (from any app: PGM, Client Portal, POSweb, Mobile app).
PersonalTrainingBookingCancelled - The booking for Personal Training has been cancelled (from any app: PGM, Client Portal, POSweb, Mobile app).
UserCardScanned - There was an attempt (successful or not) to access a particular club and zone by card, fingerprint or QR code scan.
UserModified - The personal data of any user (both guest and members) has been modified.
UserPresenceChanged - The club member has entered the club (as a result of a card scan or marking presence in POSweb).

A new webhook is added in R93:

AgreementAnswerModified - The agreement answer of a user is modified.

How to see what data is sent in a webhook?

To see data fields sent by a webhook event please add new (or use existing) webhook definition in PGM (it may be fake url added for a while) and open "Subscribed events" window.

There you can see example payload for each event by clicking information icon next to event's name.

Before you start

To be available, this feature has to be enabled by the Perfect Gym Team for your company.
Webhooks can be edited and viewed only by your employees with the properly assigned system permissions. Please check, if you or a given club employee has the right permissions set in the: PGM-> Clubs -> Employes-> System permissions (System administration - > Automation Center - > Webhooks: View&Edit and System administration - > Automation Center - > View)

Instruction

How to set up a Webhook?

Go to the PGM -> Automation Centre -> Webhooks -> Webhooks list
Click on the Add Webhook button.
Fill in the necessary information in a pop-up window which will open (1) and (2).
1. Name - friendly name to easily distinguish this particular configured Webhook in case you have many.
2. Secret - it's like a password, it is used to sign requests so that the target system can verify if the sender is the Perfect Gym.
  (For your convenienve you can copy the Secret to the clipboard)
3. URL - your (or other target) system url to be called by Perfect Gym system.
4. Click on the Save button.
Perform a test (Optional):
1. The Test all webhooks button will send a special Test event to all defined Webhooks.
2. After a while, in the Webhook Requests list, you should be able to find requests with the Test event. They should be marked as successful.
  If you do not see such requests, please wait a minute and refresh the list. The refresh button is located at the bottom of the list. You may also reload the page.
3. Ensure that the target system has properly received the Test event. This is at your site.

3. Subscribe a given Webhook to the selected PGM system events.

You can subscribe a Webhook to all of the possible events or some just to the selected ones, depending on your needs.
If you are not interested in some events, do not subscribe a Webhook to them.

Webhook Requests list

The Requests list shows all(*) the requests from the PGM system to the configured Webhook URLs.
Each request has a status informing if it was successful.
There are also windows where you can see what payload has been sent and the response (**) received by PerfectGym from Webhook's target.

You can retry sending a given request by clicking the appropriate button.

* - older requests will be irreversibly removed from the list.
** - only the first 1000 characters of the received response are visible.

Technical requirements for the target system

Webhook's target must:

Return HTTP response with 2xx HTTP status code
Return response within 5 seconds

Webhook's target should:

Be prepared to receive more than once the same request
It could be identified by the signature value
Return as short a response as possible.

Eg. HTTP body could be text: "Ok"

Webhook request - technical details

Any Webhook request is constructed as follows:

Sent as an HTTP POST
Has headers:
1. X-Perfectgym-Request: webhook_request_unique_identifier
  
  In the case of retrying to send a given webhook request, this identifier has always the same value.
2. X-Perfectgym-Signature: signature
  
  This is to make sure that the received call origin is PerfectGym. The signature value is a string calculated as follows:
  
  MD5HASH (webhook_request_unique_identifier+":"+webhook_Secret)
All date times are formatted following https://en.wikipedia.org/wiki/ISO_8601 standard.
Typically ISO 8601 format: YYYY-MM-DDThh:mm:ssZ is used - time expressed in UTC.

Body - JSON

{
  "event": event-technical-name-here,
  "triggeredDate": utc-based-time,
  "data": {
      event data fields here
    }
  }

Example of "Test" event payload:
{
  "event": "Test",
  "triggeredDate": "2020-06-01T14:44:46Z",
  "data": {
    "valueLong": 12345678,
    "valueText": "some text value",
    "nestedData": {
      "text": "nested some text value",
      "date": "2020-06-01T14:44:46Z",
      "amount": 33.78
    }
  }

Troubleshooting

If the Webhook request is not delivered to the target:

The investigation should begin with examining Webhook request details available in the Webhook requests list view.
Try the Response field - it may have some helpful information.
Be aware that the only port HTTPS 443 is allowed for webhooks. Any other will be clocked.