Booking Feed
The booking feed displays external booking data alongside the roster grid so supervisors can make informed staffing decisions. Bookings from systems like Planyo appear as context while planning shifts -- they are not converted into shifts automatically.
How It Works
- An external booking system sends a webhook to Vuoro when a new booking is confirmed.
- Vuoro stores the booking and maps it to a location using configured source mappings.
- Supervisors see the bookings on the roster grid while planning shifts.
External System → Webhook → Vuoro → Roster Grid
Setting Up a Booking Source
1. Get Your Webhook URL
- Navigate to Settings > Booking Sources.
- Your webhook URL and secret are shown in the Webhook Configuration section.
- Copy the URL and secret -- you will need both to configure the external system.
2. Configure Source Mappings
Source mappings connect site identifiers in the external system to Vuoro locations.
- In the Source Mappings section, click Add mapping.
- Enter the Source name (e.g., "planyo").
- Enter the External site ID -- the identifier the external system uses for a particular site.
- Select the corresponding Vuoro location.
- Click Create.
Repeat for each site. If a booking arrives for an unmapped site, it is stored but not shown on the roster grid. A warning banner appears in settings showing how many bookings are unmapped.
3. Configure the External System
In your booking system (e.g., Planyo), set up a webhook that sends a POST request to your Vuoro webhook URL when a booking is confirmed. Include the X-Webhook-Signature header for security.
Expected payload format:
| Field | Required | Description |
|---|---|---|
source | Yes | System identifier (e.g., "planyo") |
externalId | Yes | Unique booking ID in the external system |
externalSiteId | Yes | Site identifier to map to a Vuoro location |
title | Yes | Booking description |
customerName | No | Customer name |
startsAt | Yes | Start time (ISO 8601) |
endsAt | No | End time (ISO 8601) |
notes | No | Additional notes |
Webhook security: The request must include an X-Webhook-Signature header containing an HMAC-SHA256 signature of the JSON body, in the format sha256=<hex>. Use the webhook secret shown in settings as the HMAC key.
Viewing Bookings on the Roster Grid
When bookings exist for a location and date range, a Bookings row appears at the top of the roster grid, above the open shifts row. Each day cell shows the bookings for that day:
- Time and title are shown for each booking.
- Hover over a booking to see the customer name and notes.
- Days with no bookings show nothing -- no visual clutter.
The bookings row only appears when there are bookings for the visible week. Supervisors use this information to decide staffing levels while creating shifts below.
Regenerating the Webhook Secret
If the webhook secret is compromised:
- Go to Settings > Booking Sources.
- Click Regenerate Secret.
- Update the secret in the external booking system.
The old secret is immediately invalidated.
Permissions
| Action | Roles |
|---|---|
| View bookings on roster grid | Supervisors, managers, company admins |
| Manage source mappings | Company admins |
| View/regenerate webhook credentials | Company admins |