Follow

Using Web Hooks

You can publish updates from your Zen Planner database into any other online application using web hooks.  You can set up web hooks individually for several kinds of records in Zen Planner, giving you very fine-tuned control over the information that Zen Planner pushes to your external applications. 

Zen Planner currently supports web hooks for PERSON records, CLASS SESSION records, and ATTENDANCE records. Once each web hook is configured, Zen Planner will post new updates any time there is a change to that record.   

 

IMPORTANT! To read further, you'll need to be proficient in creating online applications, so grab your pocket protector (or a friend who has one) to continue.

 

Web Hooks In Zen Planner

Zen Planner implements a simple RESTful update mechanism, using HTTP POST transactions to transfer data.  Each record updated in Zen Planner will generate a separate call to your external web application, and each field in the charts below will be posted as a separate form field in the HTTP request.

Once your web service is configured as a web hook for Zen Planner to call, your web page will start receiving update messages within 5 to 10 minutes.  Web hooks are processed by a background queue, that lags behind the production database by at least 2 minutes, and may be slower if you make a high volume of updates.  This is done to maximize performance on the human-facing side of the system.

Because of the way Zen Planner updates information, it is possible for a record to be changed internally without any changes to the data that is pushed to you via a web hook.  This means that we may send you one or more web hooks containing identical data.  

While we have some mechanisms in place to limit duplicates where possible, it's very important that your service be idempotent, meaning that it can handle duplicate messages gracefully.

How To Add A Web Hook

You can register a web hook in Zen Planner by going to Setup > Web Hooks, and entering the publicly accessible URL to the web application that you want to update.  

Here is the information necessary to configure a web hook

Field

Description

Web Service URL

REQUIRED:  This is the address of the web application to call.

Account ID

OPTIONAL:  Additional data that's included with each POST that will help you identify which database is being updated.  This is especially important if you have a multi-tenant architecture that will potentially draw data from many member databases.

If this field is not present then it will be left blank in our data feed, and you will have no way of mapping the information to a specific database.

Shared Secret

OPTIONAL:  This is a secret that is used to generate the message signature described below.  The signature can be used by your system to validate that the information being POST-ed to your web service URL is valid, so it is important that this shared secret be kept in strict confidence. 

If this field is not present, then no signature will be generated and you will have no way of validating that the information you receive is authentic, and is actually from Zen Planner.

Web hooks will notify your external application if any records change from the point in time that you add the web hook.  Once you've tested your application, you may want to export some of the records to seed your application with pre-existing data.

 

Testing Web Hooks

PutsReq - https://putsreq.com/

There are several online tools that you can use to check HTTP requests (webhooks in this case). The one that we have tested is PutsReq. It’s pretty straight forward to setup click the create button and copy the PutsReq Url into the webhook configuration under Setup. If you are testing a person webhook, all you need to do is pick a person in your school and change some of that persons data to get a webhook to fire. You will need to wait a couple of minutes and refresh your PutsReq page or click on “Inspect”, if everything worked you should see the person data request listed.

 

The PERSON Web Hook

This web hook is executed any time a person is added to the Zen Planner database, or when a person's information is updated.  Zen Planner tracks many other pieces of information about a person that is NOT sent via this web hook.  And, changes to this "invisible" data may trigger a call to your external application even if the data that you see has not changed. 

Field

Type

Description

partitionId

GUID

Uniquely identifier for the database.

personId

GUID

Internal identifier for the person in Zen Planner.

familyId

GUID

Internal identifier for the family in Zen Planner.  This is used to group several people into a single family, and may be useful for you to create family group in your database

barCodeId

GUID

The bar code number assigned to each person in Zen Planner.  This is used to check students in to class using the attendance kiosk

prefix

String

Customizable field typically Mr. or Mrs found in the person profile under Salutation

primaryEmail

String

The email address of the person

firstName

String

The first name of the person

middleName

String

 

lastName

String

The last name of the person

company

String

 

gender

String

The gender of the person, either "Male", "Female", or blank.

birthDate

dateTime

 

email

String

Same as PrimaryEmail

phoneNumber

String

 

phone

String

 

address

String

 

address_street1

String

The primary address for the person.

address_street2

String

 

address_city

String

 

address_state

String

 

address_country

String

 

address_postal

String

Zip Code or Postal Code if outside USA

Status  

String

The status of the person, will be one of the following: "PROSPECT", "STUDENT", "ALUMNI", or blank. 

schoolName

String

Business Name configured during Setup

schoolURL

String

The business member connect address

photoURL

String

Person's profile photo

primaryInstructor

GUID

Unique ID to a person's staff profile in Zen Planner

primaryInstructorName

String

A person's instructor profile name, may be different than their person first/last name

assistantInstructor

GUID

Unique ID to a person's assistant staff profile in Zen Planner

inquiryDate

dateTime

The date when the person record was created

signupDate

dateTime

This date is configurable in studio via person updates, imports or can also be set when a program record is first assigned.

trialEndDate

dateTime

Free Trial end date

lastLogEntry

dateTime

No longer used

lastUpdated

dateTime

When the person data was last updated

personGroups 

String

should be a comma separated list of the groups a person is in

 

The CLASS SESSION Web Hook

This web hook is executed any time a class, appointment, or private lesson is added to the calendar in Zen Planner.  For recurring classes, this means that a separate transaction will be sent to you for each session of the class.  Zen Planner lists classes  

Field

Type

Description

partitionId

string

Uniquely identifier for the database in your remote system.  This is the value configured in the setup section when you created the webhook.

timestamp

dateTime

The UTC time that this transaction was generated. 

signature

string

Message signature uses the "shared secret" to authenticate that this message came from Zen Planner.  See below for details on how the signature is generated.

partitionId

guid

Internal identifier for the database in Zen Planner

appointmentId

guid

Internal identifier for the class session in Zen Planner

name

string

The name of the class or appointment

beginDate

dateTime

The date and time that this class session begins

durationMinutes

integer

The length of time (in minutes) that this class session runs.

staffId

guid

Internal identifier for the staff member responsible for this class.

staffFirstName

string

First name of the staff member responsible for this class

staffLastName

string

Last name of the staff member responsible for this class

location

string

Location where this class is held

 

The ATTENDANCE Web Hook

This web hook is executed every time a person attends a class or makes a reservation to attend a class.  It is essentially the intersection between people and class sessions, and can potentially generate A LOT of data.

Field

Type

Description

timestamp

dateTime

The UTC time that this transaction was generated. 

partitionId

guid

Internal identifier for the database in Zen Planner.

personId

guid

Internal identifier for the person in Zen Planner.

familyId

guid

Internal identifier for the family in Zen Planner.  This is used to group several people into a single family, and may be useful for you to create family group in your database

barCodeId

string

The bar code number assigned to each person in Zen Planner.  This is used to check students in to class using the attendance kiosk

prefix

string

Prefix or salutation for each person.  Examples are "Mr.", "Ms.", and "Mrs."

firstName

string

The first name of the person

middleName

string

The middle name of the person

lastName

string

The last name of the person

gender

string

The gender of the person, either "Male", "Female", or blank.

birthDate

dateTime

The birth date of the person

email

string

The email address of the person

phone

string

The primary phone number for the person

address

string

The primary address for the person.

status

string

The status of the person, will be one of the following: "PROSPECT", "STUDENT", "ALUMNI", or blank.

appointmentId

guid

Internal identifier for the class session in Zen Planner

name

string

The name of the class or appointment

beginDate

dateTime

The date and time that this class session begins

durationMinutes

integer

The length of time (in minutes) that this class session runs.

staffId

guid

Internal identifier for the staff member responsible for this class.

staffFirstName

string

First name of the staff member responsible for this class

staffLastName

string

Last name of the staff member responsible for this class

location

string

Location where this class is held

attendanceId

guid

Internal identifier for the attendance record

isAttendance

boolean

TRUE if the person has actually attended the class, otherwise FALSE.

isRsvp

boolean

TRUE if the person has reserved this class (usually via the member website), otherwise FALSE.

isFreeTrial

boolean

TRUE if this person is attending this class as a "free trial class", otherwise FALSE.  Website visitors can register for a free trial class online, and staff members can also add people directly to classes as free trials.

isDropIn

boolean

TRUE if this person is attending this class as a "drop in", otherwise FALSE.  Drop-Ins allow people to pay a one-time drop-in fee to attend a class that they don't have a membership in.

isMakeup

boolean

TRUE if this person is attending this class as a "make-up", otherwise FALSE.  Make-Ups allow members to use their current membership to attend a class that they're not enrolled in.  This requires approval from a staff member.

Field

Type

Description

timestamp

dateTime

The UTC time that this transaction was generated. 

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

0 Comments

Article is closed for comments.
Powered by Zendesk