Venue
Venue iframe
GET
For products with
Replace
Parse incoming messages with
2. Listen for
inventorySelectionType: SEATMAP. Returns an HTML page that renders the Headout-hosted seat selection UI. Embed this endpoint as an iframe in your integration. Domain whitelisting required — contact the Headout partnerships team to register your domain.
The seatmap iframe is a Headout-hosted, fully interactive seat selection UI. Embed it to support seatmap products without building custom seat selection. The endpoint returns a rendered HTML page — not a JSON payload. No API key is required; access is controlled by domain allowlisting.
Domain whitelisting
The iframe enforces an allowlist of permitted embedding domains. Before going live, contact the Headout partnerships team and provide the domain(s) you intend to embed the iframe on. Headout will add your domain toALLOWED_DOMAINS.
- Requests from domains not on the allowlist return
403 Forbidden. - The allowlist is matched against the browser-sent
Refererheader. - A request whose
Refereris from an unregistered domain returns403. The browser defaultReferrer-Policy(strict-origin-when-cross-origin) is fine: the allowlist matches on the origin. Do not applyReferrer-Policy: no-referrer. - Subdomains of a whitelisted domain are automatically permitted — whitelisting
example.comalso allowswww.example.com. - The iframe sets a
Content-Security-Policy: frame-ancestorsresponse header scoped to your domain to prevent embedding from unauthorised origins.
Sandbox needs no whitelisting.
https://www.sandbox-headout.com does not check the Referer header and allows embedding from any origin (frame-ancestors *), so you can embed from localhost or any development host without registering it. Whitelisting applies to production only: ask the Headout partnerships team to register your production domains ahead of launch.Embedding
Add the iframe to your page with the product ID substituted in thesrc URL:
3023 with the actual product ID. To test against sandbox, use https://www.sandbox-headout.com as the host and one of the sandbox seatmap test products. Also replace every https://www.headout.com postMessage target origin and event.origin check below with https://www.sandbox-headout.com, otherwise the handshake silently never completes. The iframe container must have a defined height — height="100%" requires the parent element to have an explicit height set, otherwise the iframe collapses to 0px and nothing renders.
postMessage events
The iframe communicates with the parent page viawindow.postMessage. All messages in both directions are JSON-stringified in the following envelope:
JSON.parse(event.data).
Initialisation sequence
The iframe does not load seats automatically. After embedding, you must complete the handshake and pass the selected show slot. 1. Sendinit once the iframe has loaded
iframeInitCompleted, then send initPlugin
Without
initPlugin the map renders empty — no seats will be displayed.
Events then arrive in this order: iframeInitCompleted, initializingSeatmapStarted, initializingSeatmapCompleted, inventoryUpdateStarted, inventoryUpdateCompleted; seat events follow user interaction.
Outbound events
All outbound events follow the envelope{ "type": "...", "data": { ... } }.
Map lifecycle
Seat events
Handling
onSeatSelectionSubmitted:
You can read the current selection at any time from the latest onSeatSelectionChanged seats array.
Inventory events
Emitted on initial seatmap load (afterinitPlugin) and on every subsequent setInventorySlot call.
inventoryMap is keyed by seat id (SE-…) and holds the whole slot’s inventory, so do not cap inbound message size tightly.
Price filter events
Zoom events
Other
Seat object
Each item in theseats array (from onSeatAdded, onSeatRemoved, onSeatSelectionChanged, and onSeatSelectionSubmitted) has the following shape:
Example seat
Inbound commands
The parent can send commands to the iframe after initialisation:
Send
selectSeats, addSeat and removeSeat only after inventoryUpdateCompleted; ids that are not in the slot passed to initPlugin or setInventorySlot are ignored.
Security
The iframe only accepts messages originating from the whitelistedparentOrigin. Send all messages to https://www.headout.com (https://www.sandbox-headout.com in sandbox) as the target origin and, in production, ensure your domain is registered in ALLOWED_DOMAINS.
Next steps
OnceonSeatSelectionSubmitted fires, pass the returned seat data to Validate to confirm availability, then proceed to Booking. Send each seat’s id as a seatCodes element to Validate and as an inventorySeatIds element to Booking; inventorySlotId is inventoryId in both requests.
Path Parameters
Product ID of the seatmap product.
Response
Seat selection HTML page rendered successfully.