Data ownership
Keep your signups in your own database, or leave.
Your signups are yours. GetWait gives you two ways to keep a copy that does not depend on us: stream every change into your own database as it happens, and export the whole list whenever you want. Use both: the stream keeps your copy current, the export is the backup and the way to backfill.
Stream signups into your own database
Register a webhook endpoint (api.md) subscribed to
signup.created, signup.verified and referral.converted. Each event is
signed, retried for about 24 hours, and delivered at least once, so your
receiver must be idempotent: the event id is the same on every retry and
every redelivery, so store it and skip what you have seen.
1. Schema (Postgres or Supabase)
Run this in the SQL editor of your database:
create table if not exists getwait_events (
event_id text primary key,
type text not null,
received_at timestamptz not null default now()
);
create table if not exists waitlist_signups (
id uuid primary key,
waitlist_id uuid not null,
email text,
status text not null,
referral_code text,
referred_by uuid,
referral_count integer not null default 0,
verified_at timestamptz,
created_at timestamptz not null
);
create index if not exists waitlist_signups_waitlist_idx
on waitlist_signups (waitlist_id, created_at);
getwait_events is the idempotency ledger; waitlist_signups is your copy.
2. Receiver
Signature rules and samples in other languages are in webhooks.md. A minimal receiver as a Next.js route handler (app/api/getwait/route.ts) or
any runtime with the Fetch API. It needs DATABASE_URL and
GETWAIT_WEBHOOK_SECRET (the whsec_... value returned once when you created
the endpoint) and the postgres
package. On Supabase use the connection pooler URL.
import { createHmac, timingSafeEqual } from "node:crypto"
import postgres from "postgres"
const sql = postgres(process.env.DATABASE_URL!)
const SECRET = process.env.GETWAIT_WEBHOOK_SECRET!
const TOLERANCE_SECONDS = 300
function validSignature(rawBody: string, header: string | null): boolean {
if (!header) return false
const parts = Object.fromEntries(
header.split(",").map((p) => p.split("=", 2) as [string, string])
)
const t = Number(parts.t)
if (!Number.isFinite(t)) return false
if (Math.abs(Date.now() / 1000 - t) > TOLERANCE_SECONDS) return false
const expected = createHmac("sha256", SECRET)
.update(`${t}.${rawBody}`)
.digest()
const given = Buffer.from(parts.v1 ?? "", "hex")
return given.length === expected.length && timingSafeEqual(given, expected)
}
export async function POST(request: Request): Promise<Response> {
const rawBody = await request.text() // verify the raw bytes, not re-serialized JSON
if (!validSignature(rawBody, request.headers.get("getwait-signature"))) {
return new Response(null, { status: 400 })
}
const event = JSON.parse(rawBody)
await sql.begin(async (tx) => {
// Claim the event id. If it is already there we processed it before.
const claimed = await tx`
insert into getwait_events (event_id, type) values (${event.id}, ${event.type})
on conflict (event_id) do nothing returning event_id`
if (claimed.length === 0) return
if (event.type === "signup.created" || event.type === "signup.verified") {
const s = event.data.signup
if (!s) return // payload was redacted after an erasure
await tx`
insert into waitlist_signups
(id, waitlist_id, email, status, referral_code, referred_by,
verified_at, created_at)
values (${s.id}, ${s.waitlist_id}, ${s.email}, ${s.status},
${s.referral_code}, ${s.referred_by_signup_id},
${s.verified_at}, ${s.created_at})
on conflict (id) do update set
waitlist_id = excluded.waitlist_id,
created_at = excluded.created_at,
referral_code = excluded.referral_code,
referred_by = excluded.referred_by,
-- events may arrive out of order: never move verified back to pending
status = case when waitlist_signups.status = 'verified'
then 'verified' else excluded.status end,
verified_at = coalesce(waitlist_signups.verified_at, excluded.verified_at),
email = coalesce(waitlist_signups.email, excluded.email)`
} else if (event.type === "referral.converted") {
await tx`
insert into waitlist_signups (id, waitlist_id, status, referral_count, created_at)
values (${event.data.referral.referrer_signup_id},
${event.data.referral.waitlist_id}, 'pending', 1, ${event.created_at})
on conflict (id) do update
set referral_count = waitlist_signups.referral_count + 1`
}
})
return new Response(null, { status: 200 })
}
How it stays correct:
- Verified first. The signature is checked over the raw body in constant
time, with a 5-minute window. A bad signature is a
400and nothing is written. - Idempotent on the event id. Claiming the id and writing the row happen
in one transaction. A retry or redelivery hits
on conflict do nothing, writes nothing, and still answers200so we stop retrying. If the transaction fails, the claim rolls back too, you answer non-2xx and we retry. - Order-tolerant. Events are not ordered.
signup.verifiedarriving beforesignup.createdcreates the row, and a latesignup.creatednever moves a verified signup back to pending. - Fast. Do the minimum and answer within 10 seconds; do slow work from your own table afterwards.
Behaviours to know:
referral.convertedcarries ids only; the receiver counts it on the referrer's row (and creates a stub row if the referrer's own event has not arrived yet; the latersignup.createdfills it in).- Events are only sent to endpoints that exist when the change happens. Backfill older signups with an export (below).
- Erasure: when you or a recipient erase a signup, queued payloads are
redacted (
data: { "redacted": true }) and undelivered events are dropped. The copy you already received is yours to erase: delete the row by id when you handle an erasure request (privacy.md).signup.removedis not an event in the MVP. - Event types you did not subscribe to are never sent; unknown future types
should be acknowledged with
200and ignored.
Export
curl -H "Authorization: Bearer $GETWAIT_SECRET_KEY" \
"https://<your-host>/api/v1/waitlists/$WAITLIST_ID/export?format=csv" \
-o signups.csv
format is csv (default) or json. The response streams, so a waitlist of
any size downloads without timing out on a buffer. Fields:
| Field | Notes |
|---|---|
id | Signup id; the same id as in webhooks |
email | As the person typed it |
status | pending or verified |
created_at, verified_at | ISO 8601 UTC; verified_at empty until confirmed |
referral_code | The signup's own share code |
referral_count | Converted referrals |
utm_source, utm_medium, utm_campaign, utm_term, utm_content, referrer | Attribution captured at join |
- Erased signups are not included. Removed signups are not included.
- Secret key only. Limited to 5 exports per hour per key, and each export is recorded in the audit log.
- Open CSV files safely. Cells that start with
=,+,-,@, a tab or a carriage return are prefixed with a'so a spreadsheet shows them as text instead of running them as a formula. If you import the CSV into a database, strip that single leading'where the next character is one of those. The JSON export is not altered.
Backfill your database from a JSON export:
curl -s -H "Authorization: Bearer $GETWAIT_SECRET_KEY" \
"https://<your-host>/api/v1/waitlists/$WAITLIST_ID/export?format=json" |
jq -r '.[] | [.id, "'$WAITLIST_ID'", .email, .status, .referral_code, .referral_count, .verified_at, .created_at] | @csv' |
psql "$DATABASE_URL" -c "\copy waitlist_signups (id, waitlist_id, email, status, referral_code, referral_count, verified_at, created_at) from stdin csv"
(Run it once, on an empty table. Rows that arrive from webhooks in the
meantime would clash on id: stage into a temp table and
insert ... on conflict (id) do nothing if you backfill a live stream.)
Leaving
Export everything, point your own forms at your own database, delete your webhook endpoints, and you are done. Nothing in the data model is proprietary: ids are UUIDs, emails are plain text, and every field above is in the export.