Integrating Webhooks
By setting up a web hook, TimeTap can send you notifications anytime your clients or staff members book an appointment for your business.
Our Notification service consists of a 3-step process:
- A client or staff member books an appointment
- TimeTap posts the notification with the appointment information as a JSON object to your webserver endpoint
- Your webserver application processes the JSON object
Requirements:
- A webserver running an endpoint application capable of receiving a POST request
Notes:
- Any update made to an appointment will cause a webhook to get fired - not just appointment booking but also appointment editing and appointment deletion
- Webhooks are specific to appointments. Any changes made to staff or client objects not involved with an appointment will not generate a webhook.
In this guide, we'll cover:
To receive a notification from TimeTap, you'll need to set up an endpoint to handle a POST request from our system. The post request will contain a JSON object (example shown below) with appointment data.
Once your endpoint is setup, provide the URL by going to Settings → Integrations in the backoffice, then scroll down to the Other Integrations section and click on the Webhook icon to expand:
With the Webhook area expanded, click the Activate Webhook button:
Enter the endpoint URL and click the "Update Webhook URL" button:
Appointment Object Relational Structure
Appointment JSON Object Structure and Example
Appointment objects have several top-level properties, whose types can be viewed here: Appointment Object Values
In addition, appointment objects also have child objects for Reasons (Service or Class), Client, Staff, Location, and an Array of Custom Fields.
Here's the basic structure of an Appointment object:
{
"top-level properties" : "...",
"reason" {
Object
},
"client" {
Object
},
"staff" {
Object
},
"location" {
Object
},
"fields" {
Array
}
}
Here's an abbreviated example of what the Appointment JSON object looks like:
Appointment JSON Object
{
"calendarid":10390617,
"businessId":20398,
"startTime":800,
"endTime":845,
"clientStartTime":800,
"clientEndTime":845,
"reason":{
"reasonId":96439,
"businessId":20398,
"visitMinutes":45,
"reasonDesc":"Service3"
},
"client":{
"clientId":2530974,
"firstName":"Jon",
"lastName":"Snow",
"emailAddress":"jsnow@castleblack.mil",
"city":"Victoria",
"notes":"Jon would like a notification before his appointment.",
},
"staff":{
"professionalId" : 42441,
"businessId":20398,
"userName":"DrJones2",
"email": "djones2@marshallcollege.edu"
"timeZoneCode":{
"timeZoneId":78,
"timeZoneCode":"America/New_York",
"timeZoneDesc":"America/New_York",
},
"location":{
"locationId":29945,
"locationName":"MyOffice",
"businessId":20398,
"locationType":"Office"
},
"fields": [
{
"required" : false,
"serviceIds" : [
107292
],
"userDefinedField" : false,
"dataType" : "AREA",
"active" : true,
"code" : "UDF",
"visibleOnScheduler" : true,
"validationRegex" : null,
"sortOrder" : 21,
"businessId" : 23144,
"hint" : null,
"filterByService" : true,
"oldFieldIds" : null,
"createdUser" : "mpbtest138",
"labelTag" : "%CUSTOM_FIELD_107740_LABEL%",
"modifiedDate" : 1488575155000,
"tagName" : null,
"modifiedUser" : "MPBTEST138",
"label" : "Comments",
"createdDate" : 1488394066000,
"value" : "These are comments ",
"extendedValue" : "These are comments ",
"validationError" : null,
"fieldValues" : null,
"visible" : true,
"schedulerPreferenceFieldDefnId" : 107740,
"mode" : "APPT",
"valueTag" : "%CUSTOM_FIELD_107740%"
},
{
"required" : null,
"serviceIds" : null,
"userDefinedField" : true,
"dataType" : "TXT",
"active" : true,
"code" : "UDF",
"visibleOnScheduler" : true,
"validationRegex" : null,
"sortOrder" : 22,
"businessId" : 23144,
"hint" : null,
"filterByService" : false,
"oldFieldIds" : null,
"createdUser" : "MPBTEST138",
"labelTag" : "%CUSTOM_FIELD_108594_LABEL%",
"modifiedDate" : 1488575322000,
"tagName" : null,
"modifiedUser" : "MPBTEST138",
"label" : "My Custom Field",
"createdDate" : 1488575322000,
"value" : "Custom field value",
"extendedValue" : "Custom field value",
"validationError" : null,
"fieldValues" : null,
"visible" : true,
"schedulerPreferenceFieldDefnId" : 108594,
"mode" : "APPT",
"valueTag" : "%CUSTOM_FIELD_108594%"
}
],
}
Object Values
Reason Object
Reason object value types can be found here: Reason Object Value Types
"reason" : {
"modifiedUser" : "MPBTEST138",
"internalDisplayName" : "Service 1",
"serviceLocations" : null,
"reasonId" : 107292,
"apptHrMin" : null,
"emailInstructions2" : null,
"taxable" : false,
"professionalServiceList" : null,
"businessId" : 23144,
"rescheduleType" : null,
"maxWaitListPerClass" : null,
"visitMinutes" : 60,
"customWorkSchedule" : 0,
"reasonType" : "SERVICE",
"numberSessions" : null,
"bufferBefore" : null,
"personal" : false,
"privateUrl" : null,
"embedCode" : null,
"screeningQuestion" : null,
"emailInstructions" : null,
"currencySymbol" : null,
"apptDayMax" : null,
"professionalId" : null,
"durationList" : null,
"quotaType" : null,
"allowOnline" : true,
"allowWaitList" : false,
"active" : true,
"price" : null,
"color" : null,
"discountedPrice" : null,
"sortWeight" : 0,
"customFieldForm" : null,
"bufferAfter" : null,
"internalName" : null,
"quotaFilled" : null,
"depositAmount" : null,
"allowPrePay" : false,
"reasonDetail" : null,
"quota" : null,
"reasonDesc" : "Service 1"
}
Return To Top
Client Object
Client objects contain top-level properties, as well as a nested array of Custom Fields.
Client object value types can be found here: Client Object Value Types
"client" : {
"excludeEmailCategoryIdList" : null,
"viewClientAccountIds" : null,
"lastName" : "Smith",
"clientAccountId" : null,
"createdDate" : null,
"country" : null,
"modifiedUser" : "MPBTEST138",
"state" : null,
"locale" : null,
"firstName" : "Josh ",
"cellPhone" : "9802221111",
"ssn" : null,
"timeZone" : {
"visible" : null,
"timeZoneCode" : "America\/New_York",
"timeZoneDesc" : "America\/New_York",
"sortOrder" : 10,
"timeZoneId" : 78
},
"allowWaitListText" : null,
"salesforceContactId" : null,
"createdUser" : "MPBTEST138",
"sex" : null,
"modifiedDate" : 1488575701889,
"address2" : null,
"fullName" : "Josh Smith",
"status" : "Active",
"city" : null,
"zip" : null,
"fields" : [
{
"required" : true,
"serviceIds" : null,
"userDefinedField" : false,
"dataType" : "TXT",
"active" : true,
"code" : "firstName",
"visibleOnScheduler" : true,
"validationRegex" : null,
"sortOrder" : 0,
"businessId" : 23144,
"hint" : null,
"filterByService" : false,
"oldFieldIds" : null,
"createdUser" : "mpbtest138",
"labelTag" : "%CLIENT_FIRSTNAME_LABEL%",
"modifiedDate" : 1488394066000,
"tagName" : "CLIENT_FIRSTNAME",
"modifiedUser" : "mpbtest138",
"label" : "First Name",
"createdDate" : 1488394066000,
"value" : "Josh ",
"extendedValue" : "Josh ",
"validationError" : null,
"fieldValues" : null,
"visible" : true,
"schedulerPreferenceFieldDefnId" : 107719,
"mode" : "CLIENT",
"valueTag" : "%CLIENT_FIRSTNAME%"
},
{
"required" : true,
"serviceIds" : null,
"userDefinedField" : false,
"dataType" : "TXT",
"active" : true,
"code" : "lastName",
"visibleOnScheduler" : true,
"validationRegex" : null,
"sortOrder" : 1,
"businessId" : 23144,
"hint" : null,
"filterByService" : false,
"oldFieldIds" : null,
"createdUser" : "mpbtest138",
"labelTag" : "%CLIENT_LASTNAME_LABEL%",
"modifiedDate" : 1488394066000,
"tagName" : "CLIENT_LASTNAME",
"modifiedUser" : "mpbtest138",
"label" : "Last Name",
"createdDate" : 1488394066000,
"value" : "Smith",
"extendedValue" : "Smith",
"validationError" : null,
"fieldValues" : null,
"visible" : true,
"schedulerPreferenceFieldDefnId" : 107720,
"mode" : "CLIENT",
"valueTag" : "%CLIENT_LASTNAME%"
},
{
"required" : true,
"serviceIds" : null,
"userDefinedField" : false,
"dataType" : "TXT",
"active" : true,
"code" : "fullName",
"visibleOnScheduler" : false,
"validationRegex" : null,
"sortOrder" : 2,
"businessId" : 23144,
"hint" : null,
"filterByService" : false,
"oldFieldIds" : null,
"createdUser" : "mpbtest138",
"labelTag" : "%CLIENT_FULLNAME_LABEL%",
"modifiedDate" : 1488394066000,
"tagName" : "CLIENT_FULLNAME",
"modifiedUser" : "mpbtest138",
"label" : "Full Name",
"createdDate" : 1488394066000,
"value" : "Josh Smith",
"extendedValue" : "Josh Smith",
"validationError" : null,
"fieldValues" : null,
"visible" : false,
"schedulerPreferenceFieldDefnId" : 107721,
"mode" : "CLIENT",
"valueTag" : "%CLIENT_FULLNAME%"
},
],
"homePhone" : "7048882233",
"clientId" : 3042662,
"stripeCustomerId" : null,
"squareCustomerId" : null,
"address1" : null,
"notes" : null,
"password" : null,
"emailAddress" : "timetaptest@gmail.com",
"language" : null,
"companyName" : null,
"county" : null,
"dateOfBirth" : null
}
Return To Top
Staff Object
Staff object value types can be found here: Staff Object Value Types
"staff" : {
"emailInstructions" : null,
"locationAccessList" : null,
"active" : true,
"embedCode" : null,
"emailFooter" : "<strong>You can contact us at:<\/strong><br\/>%STAFF_FULLNAME%<br\/>%BUSINESS_NAME%<br\/>%STAFF_EMAIL%<br\/>%STAFF_MOBILE%",
"acceptAppointments" : true,
"internalName" : null,
"professionalId" : 42441,
"googleSyncPeriod" : "",
"businessId" : 23144,
"mobilePhone" : "",
"locationsWithSchedule" : null,
"locale" : "en-US",
"sortWeight" : 0,
"excludeEmailCategoryIdList" : null,
"imageUrl" : null,
"timeZone" : null,
"privateUrl" : null,
"email" : "timetaptest@gmail.com",
"firstDayOfWeek" : 0,
"phone" : null,
"newApptSms" : false,
"staffProfile" : null,
"internalDisplayName" : "mpbtest138",
"userName" : "MPBTEST138",
"googleSyncActive" : false,
"skypeId" : null,
"changePasswordNextLogin" : false,
"fullName" : "mpbtest138",
"securityRoleId" : 1
}
Return To Top
Location Object
Location object value types can be found here: Location Object Value Types
"location" : {
"officePhone" : null,
"zip" : null,
"active" : true,
"embedCode" : null,
"country" : null,
"internalName" : null,
"businessId" : 23144,
"address1" : null,
"city" : null,
"locationId" : 35186,
"emailAddress" : null,
"logoUrl" : null,
"sortWeight" : null,
"state" : null,
"hasWorkScheduleOrClass" : null,
"timeZone" : null,
"privateUrl" : null,
"address2" : null,
"locationType" : "Office",
"internalDisplayName" : "My Office",
"directions" : null,
"locationName" : "My Office",
"description" : ""
}
Return To Top
Custom Fields Object
Custom Field Value Types:
| Property Name | Type | Description |
|---|---|---|
| required | boolean | Signifies if the field is required when booking an appointment |
| serviceIds | integer array | Identifies which services this field is attached to |
| userDefinedField | boolean | Signifies if the field is user-generated or TimeTap system field |
| dataType | string | Signifies the type of field, ex. "TXT" = text field |
| active | boolean | Signifies if the field is active |
| code | string | Signifies if the field is user-generated or TimeTap system field |
| visibleOnScheduler | boolean | Signifies if the field is visible on the client-facing scheduler |
| validationRegex | string | Signifies a regular expression used to validate the field's value |
| sortOrder | integer | Signifies the field's display order in relation to other fields |
| businessId | integer | The account business id |
| hint | string | The "field hint" value |
| filterByService | boolean | Filters custom field by service |
| createdUser | string | The username of the user that created the field |
| labelTag | string | A special tag used to identify the field |
| modifiedDate | integer | The last date the field was modified |
| tagName | string | A special tag used to identify the field |
| modifiedUser | string | The username of the user who last modified the field |
| label | string | The field's label |
| createdDate | integer | The date on which the field was created |
| value | string | The field's value, entered by the user or user's client when booking an appointment |
| extendedValue | string | The field's value, entered by the user or user's client when booking an appointment |
| fieldValues | string | Values for LIST-type custom fields |
| visible | boolean | Signifies if the field is visible on the client scheduler |
| mode | string | Signifies if the field belongs to client record or appointment record. Ex, "CLIENT", "APPT" |
| valueTag | string | A special tag used to identify the field |
{
"required" : false,
"serviceIds" : [
107292
],
"userDefinedField" : false,
"dataType" : "AREA",
"active" : true,
"code" : "UDF",
"visibleOnScheduler" : true,
"validationRegex" : null,
"sortOrder" : 21,
"businessId" : 23144,
"hint" : null,
"filterByService" : true,
"oldFieldIds" : null,
"createdUser" : "mpbtest138",
"labelTag" : "%CUSTOM_FIELD_107740_LABEL%",
"modifiedDate" : 1488575155000,
"tagName" : null,
"modifiedUser" : "MPBTEST138",
"label" : "Comments",
"createdDate" : 1488394066000,
"value" : "These are comments ",
"extendedValue" : "These are comments ",
"validationError" : null,
"fieldValues" : null,
"visible" : true,
"schedulerPreferenceFieldDefnId" : 107740,
"mode" : "APPT",
"valueTag" : "%CUSTOM_FIELD_107740%"
},