Webhooks
Get events in your own system, with signature verification.
GetWait pushes an HTTPS POST to your server when something happens to a
signup. Use it to sync your database, notify Slack, or start an onboarding
flow. Route-level details (create, update, delete, redeliver) are in
api.md; this page is the integration guide.
Events
| Type | When |
|---|---|
signup.created | A new signup joined (once per address) |
signup.verified | The person confirmed their email |
referral.converted | A referred person confirmed, and the referrer moved |
Body envelope (Content-Type: application/json):
{
"id": "05e738f8-4da8-857e-9d19-891448412786",
"type": "signup.created",
"created_at": "2026-11-01T12:00:00.000Z",
"api_version": "2026-11-01",
"data": { "signup": { "id": "...", "email": "...", "status": "pending" } }
}
referral.converted carries ids in data.referral and no email.
Register an endpoint
import { createClient } from "@getwait/waitlist"
const client = createClient({ apiKey: process.env.GETWAIT_SECRET_KEY! })
const endpoint = await client.webhooks.create({
url: "https://example.com/api/getwait",
events: ["signup.created", "signup.verified"],
})
console.log(endpoint.secret) // whsec_... shown ONCE: store it now
Or use the dashboard (project page, webhooks). The URL must be https and
publicly reachable: loopback, private and internal addresses are rejected
(http is allowed only when the GetWait server itself runs in development).
To test locally, expose your machine with a tunnel and register the tunnel URL.
Verify the signature
Every request carries:
GetWait-Signature: t=1700000000,v1=<hex>
GetWait-Event-Id: <same as body id>
GetWait-Delivery-Attempt: 1
v1 is HMAC-SHA256(secret, "<t>.<rawBody>"), lowercase hex. Rules that
matter:
- Use the raw body bytes. Parsing and re-serializing JSON changes them and
breaks the check. In Next.js read
await request.text()first. - Compare in constant time.
- Reject a
tmore than 5 minutes from your clock (replay protection). - A header may contain several
v1=values; any match is enough.
TypeScript (SDK, recommended)
Works on Node, Bun, Deno and edge runtimes.
import { verifyWebhookSignature, type WebhookEvent } from "@getwait/waitlist"
export async function POST(request: Request) {
const rawBody = await request.text()
const result = await verifyWebhookSignature({
payload: rawBody,
header: request.headers.get("GetWait-Signature"),
secret: process.env.GETWAIT_WEBHOOK_SECRET!,
})
if (!result.ok) return new Response(null, { status: 400 }) // result.reason says why
const event = JSON.parse(rawBody) as WebhookEvent
// ...handle idempotently, keyed on event.id
return new Response(null, { status: 200 })
}
Node.js without the SDK
import { createHmac, timingSafeEqual } from "node:crypto"
export function verify(rawBody: string, header: string, secret: string) {
const parts = header
.split(",")
.map((p) => p.split("=", 2) as [string, string])
const t = parts.find(([k]) => k === "t")?.[1]
if (!t || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false
const expected = createHmac("sha256", secret)
.update(`${t}.${rawBody}`)
.digest()
return parts
.filter(([k]) => k === "v1")
.some(([, v]) => {
const given = Buffer.from(v, "hex")
return (
given.length === expected.length && timingSafeEqual(given, expected)
)
})
}
Python
import hashlib, hmac, time
def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
parts = [p.split("=", 1) for p in header.split(",")]
t = next((v for k, v in parts if k == "t"), None)
if t is None or abs(time.time() - int(t)) > tolerance:
return False
expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return any(hmac.compare_digest(v, expected) for k, v in parts if k == "v1")
Go
import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"math"
"strconv"
"strings"
"time"
)
func Verify(rawBody []byte, header, secret string) bool {
var t string
var sigs []string
for _, part := range strings.Split(header, ",") {
k, v, _ := strings.Cut(part, "=")
switch k {
case "t":
t = v
case "v1":
sigs = append(sigs, v)
}
}
ts, err := strconv.ParseInt(t, 10, 64)
if err != nil || math.Abs(float64(time.Now().Unix()-ts)) > 300 {
return false
}
mac := hmac.New(sha256.New, []byte(secret))
mac.Write([]byte(t + "."))
mac.Write(rawBody)
expected := mac.Sum(nil)
for _, s := range sigs {
if got, err := hex.DecodeString(s); err == nil && hmac.Equal(got, expected) {
return true
}
}
return false
}
Check it with curl
Sign a test body yourself and send it to your handler:
SECRET=whsec_test
BODY='{"id":"evt_1","type":"signup.created","created_at":"2026-11-01T12:00:00.000Z","api_version":"2026-11-01","data":{}}'
T=$(date +%s)
SIG=$(printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')
curl -i -X POST http://localhost:3001/api/getwait \
-H "Content-Type: application/json" \
-H "GetWait-Signature: t=$T,v1=$SIG" \
--data "$BODY"
Handle events well
- Answer fast. Return
2xxwithin 10 seconds; do slow work afterwards. Anything else (including a redirect or a timeout) is a failed attempt. - Be idempotent. Delivery is at-least-once. The event
idis identical on every retry and redelivery; store it and skip repeats. A full example with a ledger table is in data-ownership.md. - Do not rely on order.
signup.verifiedcan arrive beforesignup.created. - Ignore unknown types and fields. New ones are added without a version change (api-versioning.md).
Retries and failures
A non-2xx answer is retried after about 1 min, 5 min, 30 min, 2 h, 5 h, 8 h,
8 h: eight attempts over roughly 24 hours, then the delivery is failed. Five
failed deliveries in a row disable the endpoint
(disabledReason: "sustained_failure"); re-enable it with PATCH or in the
dashboard. Events that occur while an endpoint is disabled or does not exist
are not queued for it; backfill with an export.
Inspect and replay deliveries:
curl -H "Authorization: Bearer $GETWAIT_SECRET_KEY" \
"$BASE/api/v1/webhook-endpoints/$ENDPOINT_ID/deliveries"
curl -X POST -H "Authorization: Bearer $GETWAIT_SECRET_KEY" \
"$BASE/api/v1/webhook-endpoints/$ENDPOINT_ID/deliveries/$DELIVERY_ID/redeliver"
lastError tells you why: http_<status>, timeout, dns_error,
connection_error, tls_error, blocked_address.
Rotating a secret
Secrets are never shown again. To rotate: create a second endpoint (new secret) for the same URL, deploy a receiver that accepts either secret, delete the old endpoint, then drop the old secret.
Erasure
When a signup is erased, queued payloads for it are redacted
(data: {"redacted": true}). Handle a missing data.signup, and delete your
own copy by id (privacy.md).
See a working receiver in examples/nextjs.