---
title: "Connect your registration tool"
description: "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."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.seatlayer.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect your registration tool

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](/server-api/guests/) 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](/server-api/guests/#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:

```bash
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](/webhooks/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](/webhooks/manage-subscriptions/#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/guests**. Authentication: Secret key

```bash
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:

```json
{
  "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](/server-api/guests/#the-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](/server-api/guests/#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`:

```json title="guest.seat_chosen"
{
  "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](/server-api/guests/#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](/webhooks/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](/webhooks/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.

```js title="server/registration-bridge.js"
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`:

```js title="readRegistration for Cvent"
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`:

```js title="Routes for Cvent"
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:

```bash
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](https://developers.cvent.com/docs/webhooks/technical-requirements),
[registered for event](https://developers.cvent.com/docs/webhooks/messages/attendees/registered-for-event),
[registration modified](https://developers.cvent.com/docs/webhooks/messages/attendees/registration-modified),
[registration cancelled](https://developers.cvent.com/docs/webhooks/messages/attendees/registration-cancelled),
[update attendee](https://developers.cvent.com/documentation#/operations/updateAttendee) and the
[registration guide](https://developers.cvent.com/docs/rest-api/guides/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:

```js title="readRegistration for HubSpot"
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:

```bash
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](https://developers.hubspot.com/docs/api-reference/legacy/webhooks/guide),
[contacts](https://developers.hubspot.com/docs/api-reference/crm-contacts-v3/guide) and
[private apps](https://developers.hubspot.com/docs/apps/legacy-apps/private-apps/overview).

## 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](/server-api/guests/#several-dates-one-list-for-an-event-series)).
6. To go live, make the subscription again with your `sk_live_…` key. The test
   one keeps receiving test events only.

Source: https://docs.seatlayer.io/integrations/registration-tools/index.mdx
