**Applies to:** [Bookings API](/docs/bookings-api/what-it-is)
Learn how to receive supported event notifications related to bookings.
## Overview
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 [Bookings API](https://developer.squareup.com/reference/square/bookings-api). A visible booking in the API is one that is included in the response from calls to the [ListBookings](https://developer.squareup.com/reference/square/bookings-api/list-bookings) endpoint.
For information about general webhooks requirements, components, and processes, see [Square Webhooks](/docs/webhooks/overview).
## Requirements and limitations
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.
## How booking event notifications work
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.
Event | Description
--------------|------------
[booking.created](https://developer.squareup.com/reference/square/bookings-api/webhooks/booking.created) | A booking is created. With buyer-level permissions, the event occurs when the [CreateBooking](https://developer.squareup.com/reference/square/bookings-api/create-booking) endpoint of the API is called. With seller-level permissions, the event occurs when a booking is created by calling the API, using the Square Dashboard, or using the seller's online booking site.
[booking.updated](https://developer.squareup.com/reference/square/bookings-api/webhooks/booking.updated) | A booking is updated when the [UpdateBooking](https://developer.squareup.com/reference/square/bookings-api/update-booking) endpoint of the API is called against updatable booking properties or when updatable booking properties are modified in the Square Dashboard or on the seller's online booking site.
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.
## Subscribe to booking events
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 Console](https://developer.squareup.com/apps), open the application to which you want to subscribe.
1. In the left pane, choose **Webhooks**.
1. At the top of the page, choose **Sandbox** or **Production**. Choose [Sandbox](/docs/devtools/sandbox/overview) for testing.
1. Choose **Add Endpoint**, and then configure the endpoint:
1. For **Webhook Name**, enter a name such as **Bookings Webhook**.
1. 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](https://webhook.site) to obtain a test URL for webhook event notifications and use the obtained test URL here.
1. Optional. For **API Version**, choose a Square API version. By default, this is set to the same version as the application.
1. 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.
1. Choose **Save**.
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 Console](https://developer.squareup.com/apps) 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.
## Receive booking event notifications
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](/docs/webhooks/step3validate).
1. Respond with an `HTTP 2xx` response code within 10 seconds of receiving the notification. For more information, see [Notification Delivery SLA](/docs/webhooks-api/delivery-sla).
1. Inspect, process, store, or forward the notification.
The body of the notification is a JSON object that contains the following properties.
| Property | Description
---------|------------
`merchant_id` | The ID of the seller associated with the affected booking.
`location_id` | The ID of the seller location to provide the booked service.
`type` | The type of event: `booking.created` and `booking.updated`.
`event_id` | The unique ID of the affected booking event, which is used for [idempotency support](/docs/webhooks/step2subscribe#format-of-an-event-notification).
`created_at` | A timestamp of when the event occurred (for example, `2020-12-16T21:59:15.286Z`).
`data` | Information about the affected booking, represented by one of the following objects, depending on the event type: [BookingCreatedWebhookData](https://developer.squareup.com/reference/square/objects/BookingCreatedWebhookData) and [BookingUpdatedWebhookData](https://developer.squareup.com/reference/square/objects/BookingUpdatedWebhookData). The `data.object` property references the affected [Booking](https://developer.squareup.com/reference/square/objects/Booking) resource.
### Notifications for booking.created events
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.
```json
{
"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](https://developer.squareup.com/reference/square/objects/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](/docs/bookings-api/use-the-api#access-scopes-of-booking-data).
### Notifications for booking.updated events
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.
```json
{
"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](https://developer.squareup.com/reference/square/objects/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](/docs/bookings-api/use-the-api#access-scopes-of-booking-data).
## Test your webhooks
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 Square Dashboard**
1. Open the Square Dashboard.
* To test with Sandbox resources, open the [Developer Console](https://developer.squareup.com/apps). Under **Sandbox Test Accounts**, choose **Open** for your test account.
* To test with Production resources, open the [Square Dashboard](https://app.squareup.com/dashboard).
1. 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](https://developer.squareup.com/explorer/square/bookings-api/create-booking)
* [UpdateBooking](https://developer.squareup.com/explorer/square/bookings-api/update-booking)
**Test using cURL**
Send cURL requests to Bookings API endpoints. For more information, see the following documentation:
* [Create a booking](/docs/bookings-api/use-the-api#create-a-booking)
* [Update a booking](/docs/bookings-api/use-the-api#update-a-booking)
You can send a generic test notification from the Developer Console.
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](/docs/webhooks/troubleshooting).