Your registrations live in one tool, and SeatLayer gives each of those people a private link to choose a seat. This page shows how to join the two with the Guests API and its webhooks.
A registration tool connects through the REST API and webhooks, with one small HTTPS service of your own that has two routes. It works with any tool that can call a URL when a registration changes and that takes an update through its API. Cvent and HubSpot are outlined below as examples to adapt. They are written from each vendor’s public documentation, linked in each section, and were not run against a Cvent or HubSpot account: check each field against your own account before you rely on it.
How it fits together
- Someone registers. Your tool calls your service (the tool’s webhook).
- Your service adds that person to the event’s guest list:
POST /v1/events/:key/guests, with the tool’s own id for the person asreference. The answer has the guest’s personallink. - The guest gets the link, opens it and chooses a seat.
- SeatLayer calls your service: the
guest.seat_chosenwebhook, with the seat and yourreference. - Your service writes the seat onto the registration (the tool’s update call).
Everything SeatLayer needs from you is a secret key on your server and one webhook subscription.
Before you start
- An event that takes guests. Create it as a free event
(
bookingMode: "free") withwhoCanBook: "guests"or"both"(Who can book). - A secret key,
sk_test_…while you build andsk_live_…after. Keep it on your server. - A webhook subscription for the guest events you want to follow:
curl -sX POST "https://api.seatlayer.io/v1/webhooks" \
-H "Authorization: Bearer $SEATLAYER_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://bridge.example.com/hooks/seatlayer",
"events": ["guest.seat_chosen", "guest.seat_changed", "guest.released"]
}'The answer has the subscription and its signing secret (whsec_…), shown
only this once. An organization keeps up to 10 active subscriptions and 25 in
all; one more answers 409 webhook_subscription_limit
(Manage subscriptions).
A subscription takes the mode of the key that made it: one made with
sk_test_… receives only test events. When you go live, make a second
subscription with your sk_live_… key
(Scope delivery).
- A place for the seat in your tool: a text field or question that your team creates there once.
1. Send a registration to the guest list
/v1/events/:key/guestsSecret keycurl https://api.seatlayer.io/v1/events/$EVENT_KEY/guests \
-H "Authorization: Bearer $SEATLAYER_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"send": "email",
"guests": [
{ "name": "Billy Joe", "email": "billy.joe@example.com",
"reference": "1353661D-E479-40AC-95DF-C45F7FB20057",
"group": "Members", "language": "en" }
]
}'The answer is 201 when the guest is new and 200 when the call updated one:
{
"guests": [
{ "id": "gst_…", "reference": "1353661D-E479-40AC-95DF-C45F7FB20057",
"status": "invited", "link": "https://app.seatlayer.io/e/ev_…/invite#gsl_…", "seats": [], "…": "…" }
],
"problems": []
}The rules that matter for a bridge:
- One person, one guest. A guest with the same
reference, or the same email, is the same guest: the call updates them and never adds a second one. So you can send a registration again whenever it changes, and send your whole list again to catch up after a fault. - When the two disagree, nothing changes. If the email belongs to one guest
and the
referenceto another, that row comes back inproblemsasemail_and_reference_differ. - 1 to 1,000 guests in one call. More answers
422 too_many_guests. Send the people already registered in calls of up to 1,000. - Read
problemsevery time. A row that can’t be written is listed there as{ "index", "error", "field" }(indexcounts from 0), while the call still answers200or201for the others. - Who sends the link.
send: "email"has SeatLayer email each new guest their link, within your organization’s daily email allowance.send: "none"leaves it to you: put thelinkfrom the answer in your own confirmation email, or store it on the registration. - Groups and seats each.
groupdecides where a guest may sit and when their choice opens (Where groups sit). A registration type or ticket type usually maps to it.
When a registration is cancelled, remove the guest with
DELETE /v1/events/:key/guests/:id. It frees their seats, ends their link and
answers 204. Keep the guest’s id from the first answer beside your
registration, or find it again with GET /v1/events/:key/guests?q= and your
reference (q also matches part of a name or an email, so compare reference
on what comes back).
2. Write the seat back
SeatLayer posts each guest event to your subscription’s URL. The body is the
usual signed envelope, with the guest change in payload:
{
"deliveryId": "9b2f6c1e-…",
"occurrenceId": "…",
"event": "guest.seat_chosen",
"at": 1793667900000,
"payload": {
"eventKey": "ev_9f3a",
"seriesKey": null,
"guest": {
"id": "gst_…",
"reference": "1353661D-E479-40AC-95DF-C45F7FB20057",
"source": { "kind": "api", "label": "API" },
"name": "Billy Joe",
"email": "billy.joe@example.com"
},
"seats": [
{ "label": "H-14-22", "display": "Hall 1 · H · 14 · 22", "floor": null,
"section": "H", "row": "14", "seat": "22", "orderId": "ord_…", "orderNumber": 1042 }
],
"chosenBy": "guest",
"at": 1793667900000,
"livemode": true
}
}| Event | What to write to your tool |
|---|---|
guest.seat_chosen |
The seats in payload.seats |
guest.seat_changed |
The seats in payload.to (they replace payload.from) |
guest.released |
Nothing: the guest has no seat now, so clear the field |
payload.guest.referenceis the id you sent in step 1. It isnullfor a guest someone added by hand or from a file without one: skip those.displayis the seat as tickets print it, and the usual value to store.labelis the seat’s label on the chart.- A guest with two seats gets both in one event. On an event series, each date
sends its own event, with that date in
eventKey. - Payload details and the other two events are on Guests API › Webhooks.
Delivery rules your receiver must meet
- Verify the signature first.
X-SeatLayer-Signatureissha256=and the HMAC-SHA256 of the raw body under yourwhsec_…secret (Verify signatures). - Answer
2xxwithin ten seconds. Anything else, or no answer, is a failed attempt. - Four attempts, then it stops. SeatLayer makes the first attempt and up to three retries, 30 seconds, 60 seconds and 2 minutes apart. An event your service missed for longer than that is not sent again by itself. Failed deliveries stay listed on the subscription, and you can send one again from the dashboard (Delivery and retries).
- Catch up from the list. After an outage, read
GET /v1/events/:key/guests?status=chosen(up to 200 a page, withnextCursor) and write each guest’sseatsto your tool. - The same event can arrive twice. Keep each
occurrenceIdyou have handled, and answer2xxwithout doing the work again. - Events can arrive out of order. When a guest changes seat quickly, write
what the guest has now: read
GET /v1/events/:key/guests/:idand store itsseats.
A sample receiver
One Node.js service with both routes. readRegistration and writeSeat are the
two functions you write for your tool; the examples below fill them in.
import crypto from "node:crypto";
import express from "express";
const app = express();
const API = "https://api.seatlayer.io";
const { SEATLAYER_SECRET_KEY, SEATLAYER_EVENT_KEY, SEATLAYER_WEBHOOK_SECRET, TOOL_TOKEN } = process.env;
// Route 1: your registration tool calls this when someone registers or changes.
app.post("/hooks/registration", express.json(), async (req, res) => {
if (req.header("Authorization") !== TOOL_TOKEN) return res.status(401).end();
const people = await readRegistration(req.body); // [{ id, name, email, group }]
if (people.length === 0) return res.status(200).end();
const answer = await fetch(`${API}/v1/events/${SEATLAYER_EVENT_KEY}/guests`, {
method: "POST",
headers: {
Authorization: `Bearer ${SEATLAYER_SECRET_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
guests: people.map((person) => ({
name: person.name,
email: person.email,
reference: person.id,
group: person.group,
})),
}),
});
// Not written: answer an error, so your tool sends the registration again.
if (!answer.ok) return res.status(502).end();
const { problems } = await answer.json();
for (const problem of problems) {
console.warn("guest not written", people[problem.index].id, problem.error);
}
return res.status(200).end();
});
function signedBySeatLayer(rawBody, header) {
if (typeof header !== "string" || !/^sha256=[0-9a-f]{64}$/i.test(header)) return false;
const expected = crypto.createHmac("sha256", SEATLAYER_WEBHOOK_SECRET).update(rawBody).digest();
const provided = Buffer.from(header.slice("sha256=".length), "hex");
return provided.length === expected.length && crypto.timingSafeEqual(provided, expected);
}
const seatText = (seats) => seats.map((seat) => seat.display).join("; ");
// Route 2: SeatLayer calls this when a guest's seats change.
app.post("/hooks/seatlayer", express.raw({ type: "application/json" }), async (req, res) => {
if (!signedBySeatLayer(req.body, req.header("X-SeatLayer-Signature"))) {
return res.status(401).send("invalid signature");
}
const delivery = JSON.parse(req.body.toString("utf8"));
const { guest, seats, to } = delivery.payload;
// Handled before, or not a person from your tool: nothing to do.
if (guest.reference === null || (await alreadyHandled(delivery.occurrenceId))) {
return res.status(200).end();
}
if (delivery.event === "guest.seat_chosen") await writeSeat(guest.reference, seatText(seats));
if (delivery.event === "guest.seat_changed") await writeSeat(guest.reference, seatText(to));
if (delivery.event === "guest.released") await writeSeat(guest.reference, "");
await markHandled(delivery.occurrenceId);
return res.status(200).end();
});
app.listen(3000);alreadyHandled and markHandled are a table of occurrenceId values in your
own database. If writeSeat throws, the route answers an error and SeatLayer
tries the delivery again.
Example: Cvent
Cvent sends registrations through its webhooks and takes the seat back through its REST API. Both are set up in your own Cvent account. For questions about enabling webhooks in your account, Cvent’s documentation points you to your Cvent account manager.
Their webhook to your service. Cvent posts JSON to the URL you give it, with
the token you chose in the Authorization header. When you switch a webhook on,
Cvent first sends a GET to that URL and expects 200. Subscribe to these
three:
Cvent eventType |
Do |
|---|---|
InviteeOrGuestAccepted |
Add the guest |
InviteeOrGuestModified |
Send the guest again: the same reference updates them |
InviteeOrGuestCancelled |
Remove the guest |
Each body carries the people in message:
function readRegistration(body) {
if (body.eventType !== "InviteeOrGuestAccepted" && body.eventType !== "InviteeOrGuestModified") return [];
return body.message.map((invitee) => ({
id: invitee.inviteeStub,
name: invitee.fullName,
email: invitee.email,
group: invitee.registrationType || undefined,
}));
}Cvent adds the event type and a message id to the path it posts to
(/<your-path>/<EventType>/<message id>), and checks the URL with a GET
first. So mount route 1 on a pattern, and answer the GET:
const cventPath = /^\/hooks\/registration(\/.*)?$/;
app.get(cventPath, (req, res) =>
res.status(req.header("Authorization") === process.env.TOOL_TOKEN ? 200 : 401).end());
// Mount route 1 on cventPath instead of "/hooks/registration".For InviteeOrGuestCancelled, find the guest by inviteeStub and remove them,
as step 1 describes.
Your update call to Cvent. Write the seat as the answer to a question your planner added to the event, with Cvent’s Update Attendee call:
curl --request PUT "https://api-platform.cvent.com/ea/attendees/$ATTENDEE_ID" \
--header "Authorization: Bearer $CVENT_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"status": "Accepted",
"event": { "id": "'$CVENT_EVENT_ID'" },
"contact": { "id": "'$CVENT_CONTACT_ID'" },
"admissionItem": { "id": "'$CVENT_ADMISSION_ITEM_ID'" },
"answers": [
{ "question": { "id": "'$SEAT_QUESTION_ID'" }, "value": ["Hall 1 · H · 14 · 22"] }
]
}'status,event.idandcontact.idare required, and so isadmissionItem.idfor a registered attendee. Read the attendee first (GET /ea/attendees/{id}) and send back what it has, with the seat answer added.- The webhook’s
inviteeStub,contactStubandeventStubname the attendee, the contact and the event. Check with one attendee that they are the ids the REST API takes before you rely on it. - Cvent’s REST API takes an OAuth 2.0 token (client credentials). Writing one seat is two calls: the read, then the update.
Written from Cvent’s developer documentation: technical requirements, registered for event, registration modified, registration cancelled, update attendee and the registration guide.
Example: HubSpot
Here the list lives in a CRM: your team marks the contacts to invite, and the seat lands on the contact.
Their webhook to your service. In a HubSpot app of your own, subscribe to
contact.propertyChange for a property your team sets when someone is invited
(a checkbox such as “Invited to the gala”). HubSpot posts a JSON array of up to
100 notifications. Each one has the contact’s id in objectId, not the person’s
details, so read the contact before you add the guest:
async function readRegistration(notifications) {
const invited = notifications.filter(
(note) => note.propertyName === "invited_to_gala" && note.propertyValue === "true",
);
return Promise.all(invited.map(async (note) => {
const response = await fetch(
`https://api.hubapi.com/crm/v3/objects/contacts/${note.objectId}?properties=email,firstname,lastname`,
{ headers: { Authorization: `Bearer ${process.env.HUBSPOT_TOKEN}` } },
);
const contact = await response.json();
return {
id: String(note.objectId),
name: `${contact.properties.firstname} ${contact.properties.lastname}`.trim(),
email: contact.properties.email,
};
}));
}- HubSpot signs its requests. Validate the signature as HubSpot’s documentation describes, in place of the token check in the receiver.
- HubSpot waits five seconds for an answer and sends a failed notification again, up to 10 times over 24 hours.
propertyValueis the property’s new value as text. Log one notification to see what your property type sends before you match on it.- The calls to HubSpot use a private app’s access token as a Bearer token.
- One HubSpot request becomes one
POST …/guestscall: 100 notifications fit well inside the 1,000 guests a call takes.
Your update call to HubSpot. Create a single-line text property on contacts
once (here seatlayer_seat), then write it:
curl --request PATCH "https://api.hubapi.com/crm/v3/objects/contacts/$CONTACT_ID" \
--header "Authorization: Bearer $HUBSPOT_TOKEN" \
--header "Content-Type: application/json" \
--data '{ "properties": { "seatlayer_seat": "Hall 1 · H · 14 · 22" } }'$CONTACT_ID is the reference SeatLayer sends back in the webhook.
Written from HubSpot’s developer documentation: webhooks, contacts and private apps.
Limits to plan for
| Limit | Value |
|---|---|
Guests in one POST …/guests call |
1 to 1,000 |
| How a guest is matched | By reference, or by email |
reference |
Up to 200 characters |
| Rows in one file import | 20,000 |
Guests in one POST …/guests/send call |
1,000 ids, or a filter |
| Webhook attempts | The first, then up to three retries (30 s, 60 s and 2 min apart) |
| Webhook answer time | Ten seconds |
| Webhook subscriptions | 10 active, 25 in all, for an organization |
| Invitation emails | Your organization’s daily allowance |
- A subscription is for your whole organization, not one event. Check
payload.eventKeywhen you run more than one event. - The
guest.*events are not in the server SDKs’ typed lists, and the SDKs have no guest methods: call the routes over HTTP, as above.
Check it end to end
- With a
sk_test_…key, make a test event and a test subscription. - Register one person in your tool. Confirm a guest appears in
GET /v1/events/:key/guestswith yourreference. - Open the guest’s
link, choose a seat and confirm. - Confirm the seat is on the registration in your tool.
- On a single event, change the seat on the same link, then free it with
POST /v1/events/:key/guests/:id/release. Confirm your tool follows both. On an event series a guest can’t change seats, andreleaseanswers409 series_seats_unavailable(Several dates). - To go live, make the subscription again with your
sk_live_…key. The test one keeps receiving test events only.