Skip to content

Connect your registration tool

Send the people in your registration platform or CRM to a SeatLayer guest list through the API, and write each chosen seat back with webhooks.

Updated View as Markdown

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

  1. Someone registers. Your tool calls your service (the tool’s webhook).
  2. 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 as reference. The answer has the guest’s personal link.
  3. The guest gets the link, opens it and chooses a seat.
  4. SeatLayer calls your service: the guest.seat_chosen webhook, with the seat and your reference.
  5. 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") with whoCanBook: "guests" or "both" (Who can book).
  • A secret key, sk_test_… while you build and sk_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

POST/v1/events/:key/guestsSecret key
curl 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 reference to another, that row comes back in problems as email_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 problems every time. A row that can’t be written is listed there as { "index", "error", "field" } (index counts from 0), while the call still answers 200 or 201 for 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 the link from the answer in your own confirmation email, or store it on the registration.
  • Groups and seats each. group decides 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:

guest.seat_chosenjson
{
  "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.reference is the id you sent in step 1. It is null for a guest someone added by hand or from a file without one: skip those.
  • display is the seat as tickets print it, and the usual value to store. label is 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-Signature is sha256= and the HMAC-SHA256 of the raw body under your whsec_… secret (Verify signatures).
  • Answer 2xx within 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, with nextCursor) and write each guest’s seats to your tool.
  • The same event can arrive twice. Keep each occurrenceId you have handled, and answer 2xx without 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/:id and store its seats.

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.

server/registration-bridge.jsjs
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:

readRegistration for Cventjs
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:

Routes for Cventjs
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.id and contact.id are required, and so is admissionItem.id for 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, contactStub and eventStub name 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:

readRegistration for HubSpotjs
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.
  • propertyValue is 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 …/guests call: 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.eventKey when 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

  1. With a sk_test_… key, make a test event and a test subscription.
  2. Register one person in your tool. Confirm a guest appears in GET /v1/events/:key/guests with your reference.
  3. Open the guest’s link, choose a seat and confirm.
  4. Confirm the seat is on the registration in your tool.
  5. 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, and release answers 409 series_seats_unavailable (Several dates).
  6. To go live, make the subscription again with your sk_live_… key. The test one keeps receiving test events only.
Navigation

Type to search…

↑↓ navigate↵ selectEsc close