Beta Release
This is pre-release documentation for an API in public beta and is subject to change.
Bookings API: Handle Event Notifications

Handle Booking Event Notifications with Webhooks

Use webhooks to receive notifications when a booking is created using the API or when an API-created booking is updated using the API, the Square Seller Dashboard, or the seller's booking site. Only the application that created the webhook receives the event notifications.

Webhooks help streamline the process of managing bookings. Webhooks also enable integrating bookings with other applications to provide added value. For example, when a booking is created, you can add it to a list of upcoming appointments for the customer. When a booking is updated, you can notify the service provider of the changes.

For information about general webhooks requirements, components, and processes, see Square Webhooks.

How booking event notifications work Permalink Get a link to this section

A webhook is a subscription that registers your notification URL and the events that you want to be notified about. You can configure webhooks for the following booking events.

EventDescription
booking.createdA booking is created by calling CreateBooking.
booking.updatedAn API-created booking is updated on the Seller Dashboard, the seller's online booking site, or by calling UpdateBooking.

When an event occurs, Square collects data about the event, creates a notification, and sends the notification as a POST request to the URL of all webhooks that are subscribed to the event.

Requirements and limitations Permalink Get a link to this section

The following requirements and limitations apply to webhooks for booking events:

  • Your notification URL must be a publicly available HTTPS URL. It must also return an HTTP 2xx response code within 10 seconds of receiving a notification.

  • Applications that use OAuth must have APPOINTMENTS_READ permission to subscribe to a booking event and receive notifications.

Subscribe to booking events Permalink Get a link to this section

To subscribe to notifications about booking events, you can configure webhooks for your Square bookings application. A webhook registers the URL that Square should send notifications to, the events you want to be notified about, and the Square API version.

To configure a webhook

  1. In the Developer Dashboard, open the application to which you want to subscribe.

  2. In the navigation pane, choose Webhooks.

  3. At the top of the page, choose Sandbox or Production. Square recommends using the Sandbox environment for testing.

  4. Choose Add Endpoint, and then configure the endpoint:

    1. For Webhook Name, enter a name such as Bookings Webhook.

    2. For URL, enter your notification URL. If you do not have a working URL yet, you can enter https://example.com as a placeholder.

    3. Optional. For API Version, choose a Square API version. By default, this is set to the same version as the application.

    4. For Events, choose booking.created and booking.updated. If you want to receive notifications about other events at the same webhook URL, choose them here or configure another endpoint.

    5. Choose Save.

    Note

    In the Production environment, ignore the Enable Webhooks setting on the Webhooks page. This setting applies to webhooks for Connect v1 APIs (deprecated).

To validate your webhook configuration

You can send a generic notification from your Developer Dashboard to validate that your webhook is configured correctly.

  1. On the Webhooks page for your application, choose the webhook that you want to test.

  2. In the Endpoint Details pane, choose More, and then choose Send Test Event.

  3. Select an event and then choose Send. If the endpoint is configured correctly, the Send Test Event dialog displays the response code and notification body.

Receive booking event notifications Permalink Get a link to this section

When a booking is created or updated, Square sends a notification to any webhooks that are subscribed to the corresponding event.

To handle notifications, applications typically perform the following steps:

  1. Validate the authenticity of the notification. For more information, see Validate Notifications.

  2. Respond with an HTTP 2xx response code within 10 seconds of receiving the notification. For more information, see Notification Delivery SLA.

  3. Inspect, process, store, or forward the notification.

The body of the notification is a JSON object that contains the following properties.

PropertyDescription
merchant_idThe ID of the seller associated with the affected booking.
location_idThe ID of the seller location to provide the booked service.
typeThe type of event:
   booking.created
   booking.updated
event_idThe unique ID of the affected booking event, used for idempotency support.
created_atA timestamp of when the event occurred. For example: 2020-12-16T21:59:15.286Z
dataInformation about the affected booking, represented by one of the following objects, depending on the event type:
   BookingCreatedWebhookData
   BookingUpdatedWebhookData
The data.object property references the affected Booking resource.

Notifications for booking.created events Permalink Get a link to this section

A booking.created event is invoked when a booking is created.

The following is an example of such an event notification when a booking is created for the referenced customer (customer_id) and staff member (team_member_id) to start at the referenced location (location_id) at 2020-12-19T00:15:00Z (start_at).

{
  "merchant_id": "X0HJTBGC47AJW",
  "location_id": "V86S88SJ4S1WK",
  "type": "booking.created",
  "event_id": "424f7421-0a7d-5c04-8f53-2bae6fa5e27b",
  "created_at": "2020-12-09T00:18:33Z",
  "data": {
    "type": "booking",
    "id": "pwj8437fc4w15p:0",
    "object": {
      "booking": {
        "appointment_segments": [
          {
            "duration_minutes": 5,
            "service_variation_id": "7OIQH6BDLUPINYQQWBKEBIX3",
            "service_variation_version": 1599243170657,
            "team_member_id": "uhMVqcIyL-our2aaDSSR"
          }
        ],
        "created_at": "2020-12-09T00:18:33Z",
        "customer_id": "X447D7GA2S0Y3EJ9RJ5BFABDER",
        "customer_note": "",
        "id": "pwj8437fc4w15p",
        "location_id": "V86S88SJ4S1WK",
        "seller_note": "",
        "start_at": "2020-12-19T00:15:00Z",
        "status": "PENDING",
        "updated_at": "2020-12-09T00:18:33Z",
        "version": 0
      }
    }
  }
}

The included Booking object describes the created booking.

Notifications for booking.updated events Permalink Get a link to this section

A booking.updated event is invoked when a booking is updated.

The following is an example of such an event notification when the starting (start_at) time of the previously created booking is postponed for 15 minutes to start at 2020-12-19T00:30:00Z.

{
  "merchant_id": "X0HJTBGC47AJW",
  "location_id": "V86S88SJ4S1WK",
  "type": "booking.updated",
  "event_id": "a0c4cb7f-d024-581c-9adf-dc619fb8f9ee",
  "created_at": "2020-12-09T00:20:33Z",
  "data": {
    "type": "booking",
    "id": "pwj8437fc4w15p:1",
    "object": {
      "booking": {
        "appointment_segments": [
          {
            "duration_minutes": 5,
            "service_variation_id": "7OIQH6BDLUPINYQQWBKEBIX3",
            "service_variation_version": 1599243170657,
            "team_member_id": "uhMVqcIyL-our2aaDSSR"
          }
        ],
        "created_at": "2020-12-09T00:18:33Z",
        "customer_id": "X447D7GA2S0Y3EJ9RJ5BFABDER",
        "customer_note": "",
        "id": "pwj8437fc4w15p",
        "location_id": "V86S88SJ4S1WK",
        "seller_note": "",
        "start_at": "2020-12-19T00:30:00Z",
        "status": "PENDING",
        "updated_at": "2020-12-09T00:20:33Z",
        "version": 1
      }
    }
  }
}

The included Booking object describes the updated booking.

Test your webhooks Permalink Get a link to this section

To test your webhook with actual resources, create a booking or update an existing one in your account. Make sure to test with the same environment (Sandbox or Production) that you registered for the webhook.

The following are some ways you can trigger booking event notifications.

Test from the Seller Dashboard

  1. Open the Seller Dashboard.

  2. From the navigation pane, choose Appointments, and then follow the on-screen instructions to create or update a booking.

Test from API Explorer

Sign in to API Explorer and choose your Sandbox or Production environment. Call the following Bookings API endpoints as needed to test your webhook:

Test using cURL

Send cURL requests to Bookings API endpoints. For more information, see the following documentation:

Note

You can also send a generic test notification from the Developer Dashboard.

You should receive notifications for bookings events that you subscribe to. Square does not send notifications for events that fail.

For information about troubleshooting Square webhooks, see Troubleshoot Webhooks.