Event API Webhook Implementation Guide

This article covers in detail the Event API Webhook.

The event API has been designed to allow a merchant to take over customer communication, or extend its customer experience or process, by simply listening to events coming from Booxi. It could be used to create and send custom booking confirmation messages, or to share real-time booking status with another system, for example to greet a customer on a big screen, or to notify a clienteling app, applications are unlimited.

Table of Contents

• Event Handler
• Handler Endpoint Security
• Webhook Handler Endpoint
• Signature Validation
• Events
• Reservation Events
• Appointment Events
• Client Notification Events
• Client consent change
• Test
• Using webhooks to send notifications
• Using webhooks to capture consents

How it works

• You simply register an event handler endpoint with our webhook API, and every time that event occurs, we call your handler endpoint, passing on all the information you need.
• You can register multiple handler endpoints per event type, and the same handler endpoint for multiple event types.
• Each handler endpoint is registered for a specific merchant group.
• The event API can be used along with other account settings, such as disable sending email, or SMS, if you take over sending communication using the webhook.

Event Handler

You must create event handlers on your end, expecting specific parameters to receive the event and its associated data set.

To register your handler endpoint, you must provide us with:

• The URL of your endpoint
• Tell us if you expect a POST or a PUT.
• The list of event types (see below) to listen to.
• Make sure you validate the unique event id you receive per event, to not process the same event twice. Booxi may send the same event twice on rare occasions.
  • If the webhook is configured to be sent for a group and a merchant, to the same URL, it will be sent twice, but using the same event Id.
  • If the webhook is configured to be sent for the same merchant, but multiple webhooks with different URL, it will be sent to each URL, but again with the same event id. 
• If your endpoint requires oauth2 authentication using client credentials, you will also need to provide us the following:
  • The URL to your OAuth server's /token endpoint.
  • The client id and client secret to use when requesting the access token.
  • Optionally, a list of parameters to include when requesting the access token.
  • The name of the HTTP header to send the access token to (e.g. Authentication) and optionally, the authentication scheme to include in front of the access token (e.g. Bearer)

To modify your handler yourself - NOT Available Now

• We will provide you with credentials to authenticate and use the API (client id and secret) 
• Use the Webhook API - (USA hosting)

https://api.booxi.com/doc/event.html

Note: The total number of handler endpoints that can be registered will be limited per merchant group.

Handler Endpoint Security

Even though the communication is done using SSL (HTTPS) and should always be a server to server call, we have added additional security to prevent attacks.

• Adding a secret as a parameter
  • • You can add a secret parameter to your endpoint and we will call back your endpoint passing on that information, in order to ensure that we are the party who is calling your endpoint.
      • Ex: https://yourdomain.com/yourendpoint?secret=abcde12345
• Adding a secret in the header
  • • We can add a secret (or key) that you provided to us, in the header (var_name:value)  of each call to your endpoint. This is a more secure way to ensure that we are the party who is calling your endpoint.
      • Ex: {“secret”:”abcde12345”}
• Verifying a signature
  • • We can add a signature and timestamp in a JSON payload we send back to your endpoint, and you can compute and compare that signature (using a shared secret) on your end, to ensure that the payload was not modified by a middle man.
    • Since each event has a unique id (included in the signed data), this also protects you from repeat attacks.

Webhook Handler Endpoint

You can use any language to create your handler endpoint. Expect to receive the Event JSON object in parameter. The endpoint must return a 200 code, if not (for example returning a 400 or 500), Booxi will retry up to 30 times.

Refer to this documentation for the various object types, and the most updated version:

https://api.booxi.com/doc/event.html

Standard codes:

• Language codes : ISO 639-3
• Currency codes: ISO 4217
• Country codes: ISO 3166-1 alpha-2
• Time is in Zero Offset format (so it must be adjusted to the store time zone)

Considerations:

• The endpoint URL must use HTTPS.
• The webhook will not follow redirects
• The webhook can be configured to either POST or PUT.
• The webhook can be configured to send only a subset of the event types.
• The endpoint should return HTTP 200. Any other response will cause a retry.
• The endpoint must reply within 10 seconds (which can be configured). A timeout will cause a retry.
• The system will retry failed webhook events with an exponential backoff for up to 1 day.
• The system can send multiple webhook events at the same time. 
• The events are sent as they are generated, but this does not guarantee that they will be received in order.
• The events contain a version number. It will only be increased if the webhook model changes in a backward incompatible way.
• Oauth 2 authentication is available (optional). 

Webhook Handler Endpoint Example

{
    "id": 243999,
    "type": "appointment.created",
    "createdOn": "2024-08-20T13:06:37Z",
    "sentOn": "2024-08-20T13:06:37Z",
    "staffs": [
        {
            "id": 155304,
            "email": "john@gmail.com",
            "language": "eng",
            "lastName": "Jones",
            "position": "Owner",
            "biography": "",
            "firstName": "John",
            "canReplyTo": true,
            "translations": [
                {
                    "language": "eng",
                    "position": "Owner"
                }
            ],
            "profileImageUrl": ""
        }
    ],
    "booking": {
        "items": [
            {
                "price": {
                    "tax": "None",
                    "amount": "0.50",
                    "visibility": "Show",
                    "isStartingAt": false,
                    "amountPerHour": "0.00",
                    "amountPerPerson": "17.34"
                },
                "serviceId": 376894,
                "serviceName": "Price per person",
                "reservedStaffTimespan": {
                    "end": "2024-08-21T10:30:00Z",
                    "start": "2024-08-21T10:00:00Z",
                    "duration": 30
                },
                "reservedClientTimespan": {
                    "end": "2024-08-21T10:30:00Z",
                    "start": "2024-08-21T10:00:00Z",
                    "duration": 30
                }
            }
        ],
        "client": {
            "id": 2376756,
            "email": "mary@gmail.com",
            "lastName": "Smith",
            "presence": "Expecting",
            "timeZone": "",
            "firstName": "Mary",
            "remindBySMS": false,
            "trackingPage": {
                "viewUrl": "https://site.booxi.com/tracking/VG62IW0O7-iy_P89a2tDX9KmwM9CN3i18dAr",
                "canCancel": true,
                "canModify": true,
                "canConfirm": false
            },
            "remindByEmail": false,
            "homePhoneNumber": "+399907302536",
            "additionalRequest": "",
            "hasRequestedStaff": true,
            "mobilePhoneNumber": ""
        },
        "status": "Approved",
        "payment": {
            "paid": "0.00",
            "taxes": [
                {
                    "name": "Tax 1",
                    "rate": "0.033400",
                    "amount": "0.00"
                },
                {
                    "name": "Tax 2",
                    "rate": "0.052100",
                    "amount": "0.00"
                }
            ],
            "total": "17.84",
            "subtotal": "17.84",
            "onlinePaymentStatus": "None"
        },
        "staffId": 155304,
        "location": "Business",
        "createdBy": "Client",
        "createdOn": "2024-08-20T13:06:37Z",
        "quickNote": "",
        "merchantId": 11999,
        "modifiedBy": "Client",
        "modifiedOn": "2024-08-20T13:06:37Z",
        "clientCount": 1,
        "isCompleted": false,
        "acquisitionChannel":"e-commerce",
        "isScheduled": true,
        "locationText": "",
        "bookingMethod": "Appointment",
        "confirmationNumber": "A00343644",
        "totalStaffTimespan": {
            "end": "2024-08-21T10:30:00Z",
            "start": "2024-08-21T10:00:00Z",
            "duration": 30
        },
        "clientCommunication": "ClientOnly",
        "totalClientTimespan": {
            "end": "2024-08-21T10:30:00Z",
            "start": "2024-08-21T10:00:00Z",
            "duration": 30
        }
    },
    "clients": [
        {
            "id": 2376756,
            "email": "mary@gmail.com",
            "gender": "Unknown",
            "address": {
                "city": "Dallas",
                "state": "",
                "street": "1 Main Ave",
                "country": "US",
                "postalCode": ""
            },
            "language": "eng",
            "lastName": "Smith",
            "createdOn": "2024-06-19T23:45:28Z",
            "firstName": "Mary",
            "modifiedOn": "2024-08-20T13:06:37Z",
            "remindBySMS": false,
            "inMailingList": false,
            "remindByEmail": false,
            "homePhoneNumber": "+399907302536",
            "membershipNumber": "",
            "mobilePhoneNumber": "+15145555555"
        }
    ],
    "surveys": [],
    "merchant": {
        "id": 11999,
        "name": "Westhaven",
        "email": "adam@gmail.com",
        "address": {
            "city": "Paris",
            "state": "",
            "street": "30 avenue Montaigne",
            "country": "TH",
            "postalCode": "75017"
        },
        "groupId": 1859,
        "currency": "EUR",
        "timeZone": "Europe/Paris",
        "bookingUrl": "https://site.booxi.com/westhavenstore",
        "websiteUrl": "",
        "description": "",
        "phoneNumber": "+2348039013999",
        "locationCode": "3624",
        "ownerStaffId": 155304,
        "translations": [
            {
                "language": "eng",
                "bookingTermsUrl": "https://custom.terms.com/",
                "bookingPrivacyUrl": "https://custom.privacy.com/es"
            }
        ],
        "bookingTermsUrl": "https://custom.terms.com/",
        "defaultLanguage": "fra",
        "profileImageUrl": "",
        "bookingPrivacyUrl": "https://custom.privacy.com/es"
    },
    "services": [
        {
            "id": 376894,
            "name": "Price per person",
            "tags": "",
            "price": {
                "tax": "None",
                "amount": "0.50",
                "visibility": "Show",
                "isStartingAt": false,
                "amountPerHour": "0.00",
                "amountPerPerson": "17.34"
            },
            "location": "Business",
            "categoryId": 53568,
            "description": "",
            "instruction": "",
            "locationText": "",
            "showDuration": true,
            "bookingMethod": "Appointment",
            "profileImageUrl": "",
            "durationForStaff": 30,
            "durationForClient": 30,
            "externalSurveyUrl": "",
            "showStaffNameOnline": true
        }
    ],
    "resources": [],
    "clientLinks": [],
    "serviceCategories": [
        {
            "id": 53568,
            "name": "Manicure",
            "description": "",
            "translations": [
                {
                    "name": "Manicure",
                    "language": "eng"
                }
            ],
            "profileImageUrl": ""
        }
    ],
    "consentActions": [
        {
            "clientId": 2376756,
"consentId": 700,
"consentVersionId": 850,
"action": "Grant",
"on": "2024-08-01T07:15:00Z",
"bookingId": "A00155304",
"bookingMerchantId": "15229"
"proxy: "None",
"usingIP": "127.0.0.1",
"usingUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36",
"usingApp": "BookNow"

        }
    ],
    "consents": [
        {
            "id": 850,
            "versionId": 700,
            "language": "eng",
            "name": "Data Retention Policy",
            "text": "Do you agree to this [policy](https://www.booxi.com/policy)?"
        }
    ]
}

Example of client consent change

{
    "id": 21506,
    "type": "client.consent.changed",
    "createdOn": "2020-01-01T08:00:01Z",
    "sentOn": "2020-01-01T08:00:02Z",
    "content": {
        "clients": [
            {
                "id": 400,
                "firstName": "Carmen",
                "lastName": "David",
                "email": "carmen.david@booxi.com",
                "homePhoneNumber": "+15552346789",
                "mobilePhoneNumber": "+15552346789",
                "presence": "Expecting",
                "remindByEmail": true,
                "remindBySMS": true,
                "additionalRequest": "",
                "hasRequestedStaff": true,
                "isAttending": true,
                "address": {
                    "street": "123 Fake St",
                    "city": "New York",
                    "state": "NY",
                    "postalCode": "10001",
                    "country": "US"
                },
                "trackingPage": {
                    "viewUrl": "https://site.booxi.com/html/tracking.html?tracking_number=unique-tracking-number&from=carmen.davis@booxi.com&validation=87547",
                    "canConfirm": false,
                    "canModify": false,
                    "canCancel": true
                },
                "timeZone": "America/New_York"
            }
        ],
        "consentActions": [
            {
              "clientId": 400,
"consentId": 700,
"consentVersionId": 850,
"action": "Grant",
"on": "2024-08-01T07:15:00Z",
"bookingId": "A00155304",
"bookingMerchantId": "15229"
"proxy: "Staff",
"usingIP": "127.0.0.1",
"usingUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36",
"usingStaffId": 205,
"usingApp": "BackOffice"

            }
        ],
        "consents": [
            {
             "id": 700,
        "versionId": 850,
        "language": "eng",
        "name": "Data Retention Policy",
        "text": "Do you agree to this [policy](https://www.booxi.com/policy)?"

            }
        ]
    }
}

 

Example of a "client notification"

{
  "id": 7,
  "type": "client.notification.sent",
  "content": 
  {
     "clientNotification":
     {
        "clientId": 145637,
        "communicationMethod": "Email" // VoiceCall, SMS, Email
        "email": "demo@booxi.com"
        "mobilePhoneNumber": "",
        "message": "This is a custom notification sent to the client."
     }
  }
}

Signature Validation

Webhook event HTTP requests can be signed to increase security and prevent middle man attacks. When configured with a secret_token, the HTTP request includes a signature to validate that the event was generated by Booxi and not modified before it reaches its destination.

• The signature is available as an HTTP header called Booxi-Signature.
• It is an HMAC built from the HTTP body, the secret token and the SHA256 hash function.
• It is encoded as hexadecimal digits.

Here are examples on how to compute the signature, in order to verify it.

Node.js

const crypto = require("crypto");

const signature crypto.createHmac("sha256", secret_token).update(http_body).digest("hex");

PHP

$signature = hash_hmac('sha256', $http_body, $secret_token);

Python

import hmac

import hashlib

signature = hmac.new(secret_token, http_body, hashlib.sha256).hexdigest()

 

When computing the signature, it's important to pass the request body as it was received. Make sure that the string encoding was not changed and that the JSON parsing is done after.

Events

Here is the list of event types you can listen to (i.e. register event handler endpoints for). There are 2 types of booking (appointments and group event reservations) each with its own event types you can listen to.

Reservation Events

These are triggered by group event reservations. Use the associated event types to register your handler endpoint.

Webhook Event Type	Event Triggers (and changed values)
reservation.created	New reservation is created by staff or client booking.confirmationNumber
reservation.status_updated	Status is changed to Approved or Canceled (by staff, client or automatically1) booking.status Group reservation is completed 1 booking.isCompleted 1The rest of the reservation must not have changed
reservation.updated	Price changed booking.items[].price.amount booking.items[].price.amountPerPerson booking.items[].price.amountPerHour booking.items[].price.visibility booking.items[].price.tax booking.items[].price.isStartingAt
reservation.updated	Communication preference changed booking.clientCommunication
reservation.updated	Requester client changed booking.client.id booking.client.firstName booking.client.lastName booking.client.email booking.client.homePhoneNumber booking.client.mobilePhoneNumber booking.client.remindByEmail booking.client.remindBySMS booking.client.additionalRequest booking.client.isAttending booking.client.hasRequestedStaff
reservation.updated	Attendee added, removed, reordered or changed booking.attendees[].clientId booking.attendees[].presence (arrived, no show..) booking.attendees[].firstName booking.attendees[].lastName booking.attendees[].email booking.attendees[].homePhoneNumber booking.attendees[].mobilePhoneNumber booking.attendees[].remindByEmail booking.attendees[].remindBySMS booking.attendees[].additionalRequest booking.attendees[].surveyResponse
reservation.remind	Send approved reservation reminder 12 (no related data) 1 Even if no attendee wants to receive any reminder 2 Reminder time set when group (not reservation) is created or modified This event is triggered when the reminder or additional reminder are due.
reservation.online_payment	Sent when a payment is made reservation.payment.onlinePaymentAmount reservation.payment.onlinePaymentStatus

IMPORTANT: Closing a group will send completed events for each reservation, which is used to send Thank You emails; however, if the user closes, re-opens, and closes again, clients will not receive the thank you email again.

Appointment Events

These are triggered by appointments. Use the associated event types to register your handler endpoints.

Webhook Event Type	Event Triggers (and changed values)
appointment.created	New appointment is created by staff or client booking.confirmationNumberNew appointment requested (no staff / no date) by client
appointment.status_updated	Status is changed to Approved/Canceled/ClientArrived/NoShow/Completed/Reopen by staff1/Requested Status is confirmed or cancelled by the client1 Status is automatically approved after delay1 booking.status booking.isCompleted Booking.client.presence Status is automatically canceled after a missing payment1 1The rest of the appointment must not have changed
appointment.updated	Staff is set, changed or removed booking.staffId
appointment.updated	Date is set, changed or removed booking.isScheduled booking.totalClientTimespan.start booking.totalStaffTimespan.start
appointment.updated	The client's requested availability (i.e. client availability) changed1 booking.clientAvailabilities[].start booking.clientAvailabilities[].end 1The requested client availability is only visible for unscheduled appointment requests.
appointment.updated	Resource is set, changed or removed appointment.items[].resourceId
appointment.updated	Service is added, removed, reordered or changed booking.items[].serviceId booking.items[].reservedStaffTimespan.start booking.items[].reservedStaffTimespan.duration booking.items[].reservedClientTimespan.start booking.items[].reservedClientTimespan.duration booking.items[].price.amount booking.items[].price.amountPerPerson booking.items[].price.amountPerHour booking.items[].price.show booking.items[].price.tax booking.items[].price.type booking.items[].surveyResponse
appointment.updated	Appointment location is changed booking.location booking.location_details (if PHONE, VIDEO, CUSTOM)
appointment.updated	Appointment client is changed booking.clientCount booking.client.id booking.client.firstName booking.client.lastName booking.client.email booking.client.homePhoneNumber booking.client.mobilePhoneNumber booking.client.remindByEmail booking.client.remindBySMS booking.client.additionalRequest booking.client.hasRequestedStaff
appointment.remind	Approved appointment reminder is sent 1 (no related data) 1 Even if the client does not want to receive any reminder This event is triggered when the reminder or additional reminder is due.
appointment.recall	Appointment recall1 is sent recall.serviceId recall.staffId recall.message 1 There are no events when the recall is created or cancelled.
appointment.online_payment	Online payment is made appointment.payment.onlinePaymentAmount appointment.payment.onlinePaymentStatus

*Note: the 'totalClientTimespan' will be 0 if the appointment is not yet scheduled.

Client Notification Events

These are triggered by the notify client feature to send custom notification to the client by email, SMS, or record a phone call that was made. Use the associated event types to register your handler endpoint.

 

Webhook Event Type	Notification Operation
client.notification.sent	New Client Notification Sent or saved. clientNotification.clientId clientNotification.communicationMethod clientNotification.email clientNotification.mobilePhoneNumber clientNotification.message

Client Consent Change

This event is triggered whenever a client grants or revokes a consent.

Webhook Event Type

Consent Operation

client.consent.changed

Consent is granted  Consent is revoked Actions that trigger this event: Appointment or reservation is booked Appointment or reservation is created from the Back Office (implied mandatory consent) Appointment client is changed from BNv3 Appointment client is changed from the Back Office (implied mandatory consent) Cancelled appointment is reopened from the Back Office (implied mandatory consent, with the same consent version) Booking is cancelled (except for cancellation through tracking page)

Test

To test your event handler endpoints, simply provide us the required information, so we can register those endpoints. You can also use tools like requestbin.com to monitor what we send you when we call an endpoint.

1. You can create a test account using
   1. 1. booxi.com/signup (USA hosting)
      2. booxi.eu/signup (Belgium hosting) - NOT Available, please contact us
2. Login to your test account using:
   1. 1. app.booxi.com (USA hosting)
      2. app.booxi.eu (Belgium hosting) 
3. Test your handler by booking appointments and reservations using Booxi. 

Using webhooks to send notifications

This section helps understanding which events and information to look for in order to send the associated notification by email or SMS.

Notification content:

• client - provide the name, email and mobile of the customer to send the message to.
• booking - provides the current booking details
  • • The date and time of the appointment
    • The service booked
    • The staff name who will provide the service
    • The address where the service will be provided
• previous booking - provides the previous booking details in case of changes
• additionalRequest - may content data pushed with the appointment, or additional information provided by the customer.
• trackingPage - provides unique urls to view or modify appointments, which can be used to allow the customer to make changes if the booking rules of the associated service allows it. 
  • • Actions that can be performed with each a url
    • Make sure to pass the client preferred language parameter to the url in order to open the tracking page in the right language. Add &lang=eng for English.
• trackingQRCodeUrl - provides a unique url to a QR image that represents this booking/client, as well as the QR code for booking/attendee.
• staffVideoConferenceUrl - if the location is set to video conference, this will be the link to join as a staff
  • • Links to join as the client and the attendees will be found here: client.videoConferenceUrl, attendees[].videoConferenceUrl
• translations - Some content (objects) may be provided in various languages for which the translations can be found in the associated objects: Staff, Service, Resources, Merchant.
  • • Each object has a translations property that contains the additional language and its translated content.
    • The data is provided by default in the Merchant default language (defaultLanguage), which means that if the client preferred language (language) does not match the merchant default language, you must use the translations.

Do not send Messages

In some cases, you should not send any message, even though you receive a webhook call. This is the case when a staff selects the option to not send a booking update notification to the client, as well as when a client books online and chooses to not send notifications to the attendees.

Check the value of content.booking.clientCommunication:

• DoNotSend: Should not send any message to the client or attendee of this booking
• ClientOnly: Should only send messages to the client of the booking.
• ClientAndAttendees: Should send messages to both the client and the attendees of this booking.

Booking Tracking Page URL

Each booking comes with a URL to view the booking online and optionally modify it. You can add parameters to the URL to automatically trigger an action based on a CTA in your email.

Use the content.booking.trackingPage.viewURL value to open the tracking page

• Make sure to add lang=XXX to this URL to open “Book Now” in the customer preferred language.
• Add action=modify to trigger the modify CTA
• Add action=cancel to trigger the cancel CTA
• Add action=confirm to trigger the confirm CTA

Check the content.booking.trackingPage.canConfirm, canModify, canCancel value to know which CTA will be available for that booking.

*Note: a tracking page URL will not be created if the client has no email address.

Staff Messages

To customize the staff messages, the events are the same as for the client, so for example when you send a confirmation message, you can also send a message to the staff, from the same event appointment.created with booking.status=Approved. Booxi does not send 2 events, as the appointment is created or updated once, you on the other hand, can send as many messages or process as many tasks as you want for that one event you receive.

Booxi currently sends the following messages to the staff

• New appointment booked for the staff
  • • By the client
    • By the staff himself
    • By another staff 
• New appointment approved 
• New appointment booked with flexible dates
• New appointment booked needs to be manually dispatched (no staff selected)
• Appointment has changed 
  • • By the client
    • By the staff himself
    • By another staff 
• Appointment has been canceled
  • • By the client
    • By the staff himself
    • By another staff 

Appointment Confirmation

Send a confirmation email when a new appointment is created or approved. In manual approval mode, an appointment can be created pending for a manual approval by the staff, and the confirmation only sent once the appointment is actually approved.

Webhook events to look for:

• event type=appointment.created and booking.status=Approved
• event type=appointment.status_updated and booking.status=Approved with client.presence=Expecting
  • • Look at previous.status != booking.status to detect the status change
• event type=appointment.updated, and booking.status=Approved and previous.status != booking.status to detect the status change

Actions:

• trackingPage.viewURL
• trackingPage.canModify (boolean indicating that modify is allowed)
• trackingPage.canCancel (boolean indicating that cancel is allowed)

Appointment request notification

Send a notification that the customer’s appointment request has been received, and will later be approved by the staff. 

Webhook events to look for:

• event type=appointment.created and booking.status=PendingStaffApproval

Actions:

• trackingPage.viewURL
• trackingPage.canCancel (boolean indicating that cancel is allowed)
  
  

Appointment changed and awaiting client to confirm changes

Send a notification that the appointment has been modified by the staff and it requires the customer to confirm the changes are ok.

Webhook events to look for:

• event type=appointment.created and booking.status=PendingClientApproval

Actions:

• trackingPage.viewURL
• trackingPage.canConfirm (boolean indicating that confirm is allowed)
• trackingPage.canModify (boolean indicating that modify is allowed)
• trackingPage.canCancel (boolean indicating that cancel is allowed)

Appointment changed notification

Send a notification that the appointment has been modified by the staff. To understand which changes were made, you can compare the booking data with the previous booking data.

Webhook events to look for:

• event type=appointment.updated

 

Actions:

• trackingPage.viewURL
• trackingPage.canModify (boolean indicating that modify is allowed)
• trackingPage.canCancel (boolean indicating that cancel is allowed)

Appointment has been canceled by the store

Send a notification that the appointment has been modified by the staff.

Webhook events to look for:

• event type=appointment.status_updated and booking.status=Cancelled, modifiedBy=staff

Actions:

• trackingPage.viewURL

Appointment has been canceled by the client

Send a notification that the appointment is now canceled, and was canceled by the client. This message allows you to make a difference between a confirmation of cancellation by the client and a booking that was canceled by the store (the previous case).

Webhook events to look for:

• event type=appointment.status_updated and booking.status=Cancelled, modifiedBy=client

Actions:

• trackingPage.viewURL

Appointment is a no-show

Send a notification to the customer for the no-show and perhaps invite the customer to book again. This email is optional, and only useful to inform the customer of consequences or ask to book again.

Webhook events to look for:

• event type=appointment.status_updated and booking.status=Approved, client.presence=NoShow

Actions:

• trackingPage.viewURL

Appointment is completed

Send a thank you email to the customer once the appointment is completed. This email is automatically sent (if the option is enabled in my business rules) once the appointment is completed, and auto completion of appointments can be configured in Booxi.

Webhook events to look for:

• event type=appointment.status_updated and booking.isCompleted=true
  • • To send a thank you message, also make sure the isCompleted has changed by comparing with the previousBooking.isCompleted

Appointment reminder

Send a reminder notification to the customer a little time before the appointment. The delay before the appointment can be configured in my business rules. You can look at the client.remindBySMS and client.remindByEmail to select the preferred communication method of the customer to send the reminder.

Webhook events to look for:

• event type=appointment.remind

Actions:

• trackingPage.viewURL

Appointment recall

Send a reminder to book a new appointment sometimes after the last appointment was completed. Booxi has a reminder programing system that will program a recall message X days after an appointment is completed. This option must be activated in Booxi.

Webhook events to look for:

• event type=appointment.recall

Reservation is completed

Send a thank you email to the customer once the group reservation is completed. Booxi automatically sends an email (if the Thank You Message option is enabled in my business rules) once the group is completed, and auto completion of groups can be configured in Booxi.

Webhook events to look for:

• event type=reservation.status_updated and booking.isCompleted=true
  • To send a thank you message, also make sure the isCompleted has changed by comparing with the previousBooking.isCompleted

Using webhooks to capture consents

This section helps understand which events and information to look for in order to capture consents.

To capture consents, register a webhook callback listening to the events mentioned below, and update your consent information database using the provided values, such as the action (i.e. whether the consent was granted or revoked), the consent details and the action details identifying the user IP address and user agent, which you can use as a proof. Other values include client ID, the ID of the booking associated with the consent action and the consent name that should be used to identify and link the Booxi consent with your third-party consent.

Webhook events to look for:

• event type=appointment.created
• event type=appointment.updated
• event type=appointment.status_updated

Relevant variables:

• "consentActions"
• "consents"

ConsentAction object

Property	Example value	Description
clientId	399	The id of the client for whom the consent was changed.
consentId	700	The id of the consent, which can be used to retrieve its details.
consentVersionId	8500	The exact version of the consent.
action	"Grant"	The consent action performed. Possible values are: Grant or Revoke
on	"2024-08-20T13:06:37Z"	The date/time at which the consent was given or revoked (UTC).
bookingId	"A00001234"	The booking ID associated with the consent.
bookingMerchantId	"15229"	Merchant ID associated with the booking where the consent was captured.
proxy	"None"	If a proxy entity was used to give consent. Possible values: None (i.e. the client gave their consent) Staff (i.e. the booking was made by the staff on behalf of the client) RequestingClient (i.e. the client reserved for a group and gave consent) API (i.e. the consent was given through API)
usingIP	"127.0.0.1"	The IP address from which the consent action was performed (see note 1 below).
usingUserAgent	"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36"	The user agent or browser that was used to perform the consent action.
usingStaffId	14325	The ID of the user who created the booking (see note 2 below); only set if "proxy" is set to "Staff".
usingApp	"BackOffice"	From where the consent was given or revoked. Options include: BackOffice, TrackingPage, BookNow, API

 

Consent object

Property	Example value	Description
id	700	The id of the consent, which can be used to retrieve its details.
versionId	850	The exact version of the consent.
language	"eng"	The language of the consent.
name	"Data Retention Policy"	The name of the consent.
text	"Do you agree to this [policy](https://www.booxi.com/policy)?"	The text content of the consent.