Registration on your own website
Four ways to take registrations outside Soventro. Every one uses the same server-side rules, so prices, invitations, approvals and the one-registration-per-person rule hold whichever you choose.
Choosing a method
| Feature | Hosted link | Embed script | Plain iframe | JSON API |
|---|---|---|---|---|
| Setup | None | Add your site, paste a snippet | Add your site, paste a tag | Turn the API on, write code |
| Types, questions and conditions | Yes | Yes | Yes | You render them from the form we return |
| Invitations and discount codes | Yes | Yes, from the page address or data-code | Yes, in the frame address | Yes, as request fields |
| Approval and waitlists | Yes | Yes | Yes | Yes |
| Card payment | On the page | Opens the hosted page | Opens the hosted page | Send people to continueUrl |
| Automatic height | Not needed | Yes | No, set a height | Not needed |
| Completion events | No | Yes | No | The response itself |
| Return to your site | Status page link, if configured | Yes | Link in the frame | Yes, confirmationUrl |
| Your branding | Full event theme | Logo, colors, optional transparent background | Same as script | Entirely yours |
Setup
In Soventro, open the event and choose Embed & API. You need permission to manage the event. Both embedding and the API are off until you turn them on, and a cloned event starts with them off.
- List each website allowed to show the form, up to 20. An entry is one exact site over https:
www.example.comandexample.comare two entries. Wildcards aren't accepted. - Optionally give a confirmation page on one of those sites.
- The event must be published. In the addresses below,
ORGandEVENTare the two parts of your hosted event address,/e/ORG/EVENT.
Embed script
Paste this where the form should appear. The link inside is what people get if the script can't run.
<div data-soventro-event="ORG/EVENT">
<a href="https://soventro.com/e/ORG/EVENT">Register</a>
</div>
<script src="https://soventro.com/soventro-embed.js" async></script>Optional attributes on the div:
data-type="vip"opens one attendee type instead of the list.data-code="EARLY20"applies a discount code. The server still checks it.data-title="Register for Summit"names the frame for screen readers.data-redirect="false"stays on the page when a confirmation page is set.data-auto-continue="true"goes straight to payment after submit, without the extra button.data-datalayer="true"pushes events towindow.dataLayerfor Google Tag Manager.data-min-height="600"sets the height before the form loads.
code, invite, ref and utm_* in your page's address are passed to the form, so existing direct links and campaign tracking keep working. To add a form after the page has loaded:
Soventro.mount(document.getElementById("signup"), {
event: "ORG/EVENT",
type: "vip",
});The form takes your organization's logo and brand colors from Soventro. If a site isn't allowed, the browser refuses the frame. After ten seconds the script replaces it with a link to the hosted page and fires an error event.
Events
Events carry the reference, status, event slug and type key. They never carry names, emails or answers, so they're safe to pass to analytics.
Soventro.on("submitted", (e) => console.log(e.reference, e.status));
Soventro.on("completed", (e) => gtag("event", "registration", { ref: e.reference }));
// Or, on the element or anything above it:
document.addEventListener("soventro:payment_required", (e) => console.log(e.detail.status));ready: the form loaded.submitted: any accepted submission.completed: confirmed with nothing to pay.received: an application or waitlist place, with nothing to do yet.payment_required: must continue to the hosted payment page. CarriescontinueUrl.error: the server refused the submission, or the frame didn't load.*withSoventro.on: all of them.
No event fires after payment, because the person has left your page by then. Payment success comes back as a visit to your confirmation page, with soventro_reference and soventro_status in its address. These parameters are a courtesy for your page and analytics, not proof of payment. For that, use webhooks.
Plain iframe
For site builders that don't allow scripts. Allowed sites only. There's no automatic height and there are no events.
<iframe
src="https://soventro.com/embed/ORG/EVENT"
title="Event registration"
style="width:100%;height:1100px;border:0">
</iframe>Don't add a sandbox attribute, because it can stop the button that opens the payment page.
Payment
Card details are never taken inside a frame or through the API. After submit, a paid registration gets a continueUrl that opens the hosted payment page, where the payment provider handles bank authentication such as 3-D Secure and any redirects, and invoices can be chosen if the event offers them.
- The link works once and lasts 60 minutes. Treat it as private to the person registering, and don't log it.
- Paid places are held for 30 minutes, the same as on the hosted page.
- After that, the attendee gets a sign-in link by email, as on any hosted registration page.
- When they finish, the status page offers a link back to your confirmation page, or to the site they came from.
Public API
No keys: it exposes only public event data and does what the public form does. Turn it on per event. Browser calls work only from allowed sites, and servers may call it without an Origin header. It doesn't read registrations back; for that, use the API with keys from your server.
1. Read the event and its public options
curl https://soventro.com/api/public/v1/events/ORG/EVENTTypes by invitation only aren't listed.
2. Read an option's questions and price
curl "https://soventro.com/api/public/v1/events/ORG/EVENT/options/vip?code=EARLY20"Returns form (questions, with their conditions), price in minor units, discount and blocked, which says why it can't be used right now. An invitation-only type answers 403 invite_required unless you add a valid invite. Show the total you get here and send it back on submit.
3. Submit
const res = await fetch("https://soventro.com/api/public/v1/events/ORG/EVENT/registrations", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
typeKey: "vip",
identity: { email: "ada@example.com", firstName: "Ada", lastName: "Lovelace" },
answers: { job_title: "COO", terms: true },
discountCode: "EARLY20", // optional
expectedTotalMinor: 80000, // optional: refused if the price moved
inviteToken: undefined, // optional
source: { utm_source: "newsletter" }, // optional
}),
});
const body = await res.json();
if (!res.ok) showErrors(body.error.message, body.error.fields);
else if (body.next === "payment") location.assign(body.continueUrl);
else showThanks(body.reference, body.status);A success is 201:
{
"registrationId": "0193…",
"reference": "REG-7K2M9Q",
"status": "awaiting_payment_method",
"next": "payment",
"continueUrl": "https://soventro.com/e/ORG/EVENT/r/0193…/continue?t=…",
"continueExpiresAt": "2027-03-01T15:00:00.000Z",
"confirmationUrl": null
}Answers use question ids from the form. Multiple choice takes an array, and consent takes true. Question conditions are applied on the server, and answers to hidden questions are dropped.
Each person has one registration per event, so retrying a success doesn't make a second one. It answers 409 already_registered, and we email that address a sign-in link. A cancelled or rejected registration is reopened, as on the hosted form.
Errors
Errors look like { "error": { "code", "message", "fields" } }, where fields maps a field or question id to its message.
403:api_disabled,origin_not_allowed,invite_required, or anotherinvite_*.404:not_found, also used for unpublished events.409:already_registered,closed,full,reopen_paid, ordiscount_*.413,415,400:too_large,unsupported_media,bad_json.422:invalid_identity,invalid_answers,invalid_request.429:rate_limited, with aRetry-Afterheader.
API with keys
For your own servers: read events, attendee types and registrations, and create registrations, across your organization. An owner or admin creates keys under Integrations and chooses what each may do. The key is shown once; Soventro keeps only a hash of it. Revoking takes effect at once. Each key shows when it was last used, and creating and revoking are in the audit log.
events:read: Read events and their attendee types.registrations:read: Read registrations, including names, emails and answers.registrations:write: Create registrations under the public rules.
Keys are server secrets. The API sends no CORS headers, so a web page can't read its answers. Don't put a key in a browser or an app.
curl "https://soventro.com/api/v1/events?limit=25" \
-H "Authorization: Bearer sov_…"Endpoints
| Request | Permission | Returns |
|---|---|---|
| GET /api/v1/events | events:read | Events, oldest first. Filter with status. |
| GET /api/v1/events/{id} | events:read | One event. |
| GET /api/v1/events/{id}/attendee-types | events:read | Types with price, capacity, access and approval. |
| GET /api/v1/events/{id}/registrations | registrations:read | Registrations with person, type, answers and money. Filter with status and updatedSince. |
| GET /api/v1/registrations/{id} | registrations:read | One registration. |
| POST /api/v1/events/{id}/registrations | registrations:write | Creates one, under the public rules. |
| GET /api/v1/me | any | The key's id, organization and permissions. |
Pages
Lists take limit (1 to 100, default 25) and cursor, and answer { "data": [...], "hasMore": true, "nextCursor": "…" }. Pass nextCursor back as cursor until hasMore is false. For an incremental sync, note the time you started and pass it as updatedSince next time.
let cursor;
do {
const url = new URL("https://soventro.com/api/v1/events/EVENT_ID/registrations");
url.searchParams.set("limit", "100");
url.searchParams.set("updatedSince", lastRun);
if (cursor) url.searchParams.set("cursor", cursor);
const page = await fetch(url, {
headers: { Authorization: "Bearer " + process.env.SOVENTRO_KEY },
}).then((r) => r.json());
for (const r of page.data) save(r);
cursor = page.nextCursor;
} while (cursor);Creating registrations
The body is the same as the public API's, and the same server rules apply: dates, invitations, eligibility, approval, capacity, discounts, required questions, and one registration per person per event. Keys get no staff overrides, and the event's public API switch doesn't apply to them. Paid registrations come back with next: "payment" and a one-time continueUrl for the attendee. Someone already registered gets 409 already_registered, with the existing registrationId if the key can read registrations, and no email is sent.
Send an Idempotency-Key header (any unique string up to 255 characters) so a retry after a timeout can't act twice. For 24 hours, the same key and body get the first answer again, with Idempotent-Replayed: true. The same key with a different body is refused with 422 idempotency_mismatch; while the first request is still running, a repeat gets 409 idempotency_in_progress.
curl -X POST https://soventro.com/api/v1/events/EVENT_ID/registrations \
-H "Authorization: Bearer sov_…" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: crm-sync-8841" \
-d '{"typeKey":"vip","identity":{"email":"ada@example.com","firstName":"Ada","lastName":"Lovelace"},"answers":{"terms":true}}'Errors have the same shape as the public API's. Also: 401 unauthorized for a missing, wrong or revoked key, and 403 insufficient_scope when the key lacks the permission. Ids from another organization answer 404.
Webhooks
Soventro can POST a JSON event to your server when something happens. Add an endpoint under Integrations, choose its events, and keep the signing secret, which is shown once.
registration.submitted: An application was submitted for review.registration.confirmed: A registration was confirmed.registration.waitlisted: Someone joined a waitlist.registration.approved: An application was approved.registration.rejected: An application was declined.registration.cancelled: A registration was cancelled.registration.substituted: A registration passed to someone else.payment.received: A payment was recorded on a registration.refund.completed: A refund was completed.ping: sent by Send test event.
POST /your/endpoint
Content-Type: application/json
Soventro-Signature: t=1793606400,v1=5f2b…
Soventro-Event-Id: 0193…
Soventro-Event-Type: registration.confirmed
Soventro-Delivery-Id: 0193…
{
"id": "0193…",
"type": "registration.confirmed",
"apiVersion": "2026-11-01",
"createdAt": "2026-11-02T10:00:00.000Z",
"data": { "registration": { "id": "0193…", "reference": "REG-7K2M-9QXA", "status": "confirmed", … } }
}Checking the signature
v1 is the hex HMAC-SHA256, keyed with your secret, of the timestamp t, a dot, and the raw request body. Compute it over the body exactly as received, compare in constant time, and refuse timestamps more than 5 minutes from your clock, so a captured request can't be replayed later.
import { createHmac, timingSafeEqual } from "node:crypto";
// rawBody: the request body exactly as received, before any JSON parsing.
function verify(secret, header, rawBody) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const t = Number(parts.t);
if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
const expected = createHmac("sha256", secret).update(t + "." + rawBody).digest("hex");
const got = Buffer.from(parts.v1 ?? "");
return got.length === expected.length && timingSafeEqual(got, Buffer.from(expected));
}Delivery
- Answer with any 2xx within 10 seconds. Anything else, a timeout or a redirect is a failure. Redirects are never followed.
- A failure is tried again, up to 8 attempts in all, about 1, 2, 4, 8, 16, 32 and 64 minutes apart, then marked failed.
- Delivery is at least once, and events can arrive out of order. Use
Soventro-Event-Idto ignore repeats, and the registration'sstatusandupdatedAtrather than arrival order. - The log on each endpoint shows every delivery, its attempts and answers, and can resend one. A resend has the same event id and body.
- The body is fixed when the event happens. Read the registration from the API if you need its current state.
- Addresses must be https, on port 443 or 8443, and resolve only to public addresses. Soventro checks the address again at each delivery, after DNS, and connects to the address it checked.
Limits
| Limit | Applies to | Value |
|---|---|---|
| Reads | API | 120 a minute per IP address |
| Discount code checks | API, embed | 30 a minute per IP address |
| Page loads | Embed, iframe | 240 a minute per IP address |
| Submissions | API, embed, iframe | 20 a minute per IP address |
| Submissions per email | API, embed, iframe | 5 in 10 minutes for each event |
| Submissions per event | API, embed, iframe | 120 a minute |
| Request size | API | 64 KB |
| Allowed sites | Embed, iframe, browser API calls | 20 per event |
| Continue link | All but the hosted link | One use, 60 minutes |
| Reads with a key | API with keys | 600 a minute per key |
| Writes with a key | API with keys | 120 a minute per key |
| Request size with a key | API with keys | 64 KB |
If you submit from your own server, every attendee shares your server's IP address, so the per-address limit applies to all of them. Calling from the attendee's browser avoids that. Tell us if a large on-sale needs more.
Security
- The embed, iframe and public API need no private credential, and none belongs in your page. API keys belong on your server only.
- Every price, rule and limit is decided on the server. Changing the page or the request can't change them.
- Only the form pages can be framed, only by your listed sites, enforced by the browser through
Content-Security-Policy: frame-ancestors. All other Soventro pages refuse framing. - The form uses no cookies and doesn't act as a signed-in person.
- The form sends messages only to the site it was opened for and accepts none back. The script accepts messages only from Soventro and only from frames it created.
- Allowed sites restrict browsers. A server can claim any origin, so the limits above are what apply to non-browser callers.