Handle Bookings Webhook Events

Webhooks help streamline the process of managing bookings. Your applications can use webhooks to receive notifications when a booking is created or updated and respond according to your application needs.

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.

Applications with buyer-level permissions only receive event notifications for bookings they created. Applications with seller-level permissions receive event notifications for any booking that is visible in the API. A visible booking in the API is one that is included in the response from calls to the ListBookings endpoint.

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

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.

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.

When an application creates or updates a booking on behalf of the seller, a webhook notification about the event is sent, although no email or SMS notification is. The application acts on behalf of the seller when it uses seller-level permissions.

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 with buyer-level permissions using OAuth must have APPOINTMENTS_READ permission to subscribe to a booking event and receive notifications.
• Applications with seller-level permissions using OAuth must have APPOINTMENTS_READ and APPOINTMENTS_ALL_READ permissions to subscribe to a booking event and receive notifications.

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 left pane, choose Webhooks.

3. At the top of the page, choose Sandbox or Production. Choose Sandbox 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 don't have a working URL yet, you can enter https://example.com as a placeholder. You can also sign on to webhook.site to obtain a test URL for webhook event notifications and use the obtained test URL here.
   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 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 the 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 window displays the response code and notification body.

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.

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

The following booking.created event is in response to the creation of a new booking. The application receiving the notification has seller-level permissions.

{
  "merchant_id": "ETCE8W0W8QDYP",
  "type": "booking.created",
  "event_id": "275e23ee-2c99-5093-963c-5097073fae2e",
  "created_at": "2021-11-30T01:58:19Z",
  "data": {
    "type": "booking",
    "id": "x0cw6tzpjbuic5:0",
    "object": {
      "booking": {
        "all_day": false,
        "appointment_segments": [
          {
            "any_team_member": false,
            "duration_minutes": 30,
            "intermission_minutes": 0,
            "service_variation_id": "GUN7HNQBH7ZRARYZN52E7O4B",
            "service_variation_version": 1613077495453,
            "team_member_id": "2_uNFkqPYqV-AZB-7neN"
          }
        ],
        "created_at": "2021-11-30T01:58:19Z",
        "creator_details": {
          "creator_type": "TEAM_MEMBER",
          "team_member_id": "2_uNFkqPYqV-AZB-7neN"
        },
        "customer_id": "K48SGF7H116G59WZJRMYJNJKA8",
        "customer_note": "Customer requested a window seat.",
        "id": "x0cw6tzpjbuic5",
        "location_id": "SNTR5190QMFGM",
        "location_type": "BUSINESS_LOCATION",
        "seller_note": "Complementary VIP service",
        "source": "API",
        "start_at": "2021-12-15T17:00:00Z",
        "status": "ACCEPTED",
        "transition_time_minutes": 0,
        "updated_at": "2021-11-30T01:58:19Z",
        "version": 0
      }
    }
  }
}

The included Booking object describes the created booking. A booking created with seller-level permissions is always deemed as accepted. When created, the booking status is automatically set to ACCEPTED. This is different from the booking created with buyer-level permissions, where the booking status is set to PENDING. Only when the seller accepts or declines the pending booking, does the booking status change from PENDING to ACCEPTED or DECLINED, respectively.

If the application receiving the event notification has buyer-level permissions, the received event data consists of a subset of the event data previously shown. For more information, see Access scopes of booking data.

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

The following booking.updated event is in response to an update to change the start_at field value of the previously created booking from 2021-12-20T17:00:00Z to 2021-12-20T19:00:00Z. No other aspect of the booking is modified. The application receiving the notification has seller-level permissions.

{
  "merchant_id": "ETCE8W0W8QDYP",
  "type": "booking.updated",
  "event_id": "6a38ffba-5c2e-5c81-87ea-dbba4ee18bc2",
  "created_at": "2021-11-30T03:56:58Z",
  "data": {
    "type": "booking",
    "id": "x0cw6tzpjbuic5:1",
    "object": {
      "booking": {
        "all_day": false,
        "appointment_segments": [
          {
            "any_team_member": false,
            "duration_minutes": 30,
            "intermission_minutes": 0,
            "service_variation_id": "GUN7HNQBH7ZRARYZN52E7O4B",
            "service_variation_version": 1613077495453,
            "team_member_id": "2_uNFkqPYqV-AZB-7neN"
          }
        ],
        "created_at": "2021-11-30T01:58:19Z",
        "creator_details": {
          "creator_type": "TEAM_MEMBER",
          "team_member_id": "2_uNFkqPYqV-AZB-7neN"
        },
        "customer_id": "K48SGF7H116G59WZJRMYJNJKA8",
        "id": "x0cw6tzpjbuic5",
        "location_id": "SNTR5190QMFGM",
        "location_type": "BUSINESS_LOCATION",
        "seller_note": "Complementary VIP service",
        "source": "API",
        "start_at": "2021-12-20T19:00:00Z",
        "status": "ACCEPTED",
        "transition_time_minutes": 0,
        "updated_at": "2021-11-30T03:56:58Z",
        "version": 1
      }
    }
  }
}

The included Booking object describes the updated booking.

If the application receiving the event notification has buyer-level permissions, the received event data consists of a subset of the event data previously shown. For more information, see Access scopes of booking data.

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 in the Seller Dashboard

1. Open the Seller Dashboard.

   • To test with Sandbox resources, open the Developer Dashboard. Under Sandbox Test Accounts, choose Open for your test account.

   • To test with Production resources, open the Seller Dashboard.

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

Test using API Explorer

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

• CreateBooking
• UpdateBooking

Test using cURL

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

• Create a booking
• Update a booking

You should receive notifications for bookings events that you subscribe to. Square doesn't send notifications for events that fail.

For information about troubleshooting Square webhooks, see Troubleshoot Webhooks.