Booking Sources

Booking Sources connect an external booking system (for example, Planyo or Johku) to Vuoro so upcoming reservations appear as a Bookings row on the roster grid. Supervisors use the feed as a staffing signal — it does not auto-create shifts.

Configuration lives under Settings > Booking Sources and is available to Company Admin only.

Source Maps

A source map tells Vuoro which internal location a given external site corresponds to. Each booking arrives with a source (e.g. planyo) and an externalSiteId (e.g. 68900:Redi). If a matching map exists, the booking is attached to that location and shows up on the roster grid. If no map exists, the booking is stored but hidden from the grid until you add a mapping — a yellow banner on this page shows how many unmapped bookings are currently sitting in the queue.

Add a source map

1. Click Add mapping.
2. Fill in:
   • Source — the external system identifier (e.g. planyo).
   • External Site ID — the value Planyo / Johku sends for that site.
   • Location — pick the Vuoro location the bookings should attach to.
3. Click Save.

You can add multiple maps per source — one per external site — as long as the combination of (source, externalSiteId) is unique.

Retroactive linking

When you create a new source map, Vuoro scans the bookings table for any existing unmapped bookings that match (source, externalSiteId) and attaches them to the location you picked. You do not need to re-trigger the webhook.

Unmapped external keys

Bookings arriving with an unknown externalSiteId are stored (so nothing is lost) but their locationId is NULL, which hides them from the roster grid. The unmapped-count banner lets you spot when an external system has started sending a new site ID you have not mapped yet.

Webhook Configuration

The Webhook Configuration section on this page shows two URLs and a shared secret.

Field	Purpose
Webhook URL	Generic endpoint: POST /api/v1/webhooks/bookings/{tenantToken}. Use for custom integrations.
Planyo Webhook URL	Variant that accepts Planyo's native notification payload: POST /api/v1/webhooks/bookings/{tenantToken}/planyo.
Webhook Secret	Shared secret used to sign incoming payloads.

Configuring your external system

Paste the webhook URL into the external system's notification settings. Every delivery must include the header:

x-webhook-signature: sha256=<hex-hmac-of-raw-body>

The signature is an HMAC-SHA256 of the raw request body using the webhook secret. Vuoro verifies it with a timing-safe comparison before accepting the delivery. Deliveries without a valid signature are rejected.

Expected payload shape

For the generic endpoint:

Field	Required	Description
source	Yes	e.g. planyo, johku.
externalId	Yes	Unique ID in the external system. Used for deduplication — resending the same (source, externalId) upserts.
externalSiteId	Yes	Looked up in source maps to resolve the location.
title	Yes	Booking title shown on the grid card.
customerName	No	Shown in hover detail.
startsAt, endsAt	Yes / No	ISO timestamps. endsAt is optional.
notes	No	Free-text.

The Planyo variant accepts Planyo's native notification format and auto-transforms it into the shape above. It filters for reservation_confirmed and new_reservation notifications only.

Rotating the secret

Click Regenerate Secret if you suspect the current secret has been exposed. Regenerating invalidates immediately — deliveries signed with the old secret will be rejected, so update your external system before or right after regenerating.

Testing

There is no in-app "send test delivery" button today. To verify end-to-end, trigger a real or test booking in your external system and check that it appears on the roster grid for the configured location.

See also

• Booking Feed — the supervisor-facing view of bookings on the roster grid.