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 comes through as ‘secret’ and it is unencrypted. |
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 |
|
|
|
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. |
|
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 |
|
|
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. |