Skip to Content

Webhooks

Get a signed HTTP POST when guests RSVP, cancel, move off the waitlist or check in, and when events change.

Register a URL and WhoComing sends it a signed POST every time something happens. Deliveries are written in the same database transaction as the change itself, so none are lost, and they are retried until your server answers with a 2xx.

Register an endpoint

curl -X POST https://api.whocoming.com/v1/webhook-endpoints \
  -H "Authorization: Bearer wc_test_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/whocoming","events":["rsvp.created","rsvp.cancelled"]}'
{
  "id": "whk_...",
  "mode": "test",
  "url": "https://example.com/hooks/whocoming",
  "events": ["rsvp.created", "rsvp.cancelled"],
  "disabled_at": null,
  "created_at": "2026-12-01T15:04:05Z",
  "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
}

Store secret now: it is shown only in this response. Leave out events to receive every type. Endpoints belong to a mode: one registered with a test key receives only test-mode events. The number of endpoints depends on your plan.

Which URLs are accepted

  • https:// on a public host name, such as https://example.com/hooks/whocoming.
  • Not accepted: plain http://, a user name or password in the URL, single-word host names, local names (.local, .internal, .lan, .localhost, .home.arpa), and private, loopback, link-local or cloud metadata addresses written as an IP (10.x, 192.168.x, 127.0.0.1, 169.254.169.254, [::1] and the like). The answer is 400 validation_failed on url.
  • When a delivery is sent, the host name is looked up again, and an address that turns out to be private is refused for that attempt. So a name that points at your internal network never receives a delivery, even if it was public when you registered it.

To receive deliveries on your own computer, use a tunnel (see Testing locally).

Event types

TypeSent when
rsvp.createdA guest RSVPed, from any source: widget, hosted page, API or dashboard.
rsvp.updatedAn RSVP changed: name, guests, answers or status. Also sent when a guest re-RSVPs after cancelling.
rsvp.cancelledAn RSVP was cancelled or deleted. A deleted RSVP's data has deleted: true.
rsvp.promotedA spot opened and a waitlisted guest moved to going.
rsvp.checked_inA guest was checked in at the door.
event.createdAn event was created, including each occurrence of a series.
event.updatedAn event's details changed.
event.cancelledAn event was cancelled.

The envelope

Every delivery has the same outer shape:

{
  "id": "dlv_7b2d4f6h8j0l2n4p6r8t",
  "type": "rsvp.created",
  "created_at": "2026-12-01T15:04:05Z",
  "mode": "live",
  "data": {
    "id": "rsvp_9a2c4e6g8i0k2m4o6q8s",
    "event_id": "evt_demo0000000000000001",
    "mode": "live",
    "status": "going",
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "guests": 1,
    "answers": { "deck": "Mono red aggro" },
    "source": "embed",
    "locked": false,
    "checked_in_at": null,
    "created_at": "2026-12-01T15:04:05Z",
    "updated_at": "2026-12-01T15:04:05Z"
  }
}

For rsvp.* types, data is the RSVP as the API returns it. For event.* types, data is the event, without counts and url. A locked RSVP arrives with name, email and answers set to null. When an RSVP is deleted (by the organizer, or by erasing a guest), rsvp.cancelled carries identifiers only, with "deleted": true.

source says where the RSVP came from: embed (the widget), page (a WhoComing hosted page), api (a secret key) or dashboard (added by the organizer).

The exact schema of every type is in the webhooks section of the OpenAPI document, and the SDK has matching types (RsvpCreatedWebhook and so on), so a switch on event.type narrows event.data.

Headers

Deliveries follow Standard Webhooks:

HeaderValue
webhook-idThe delivery ID, the same as the envelope's id.
webhook-timestampUnix time in seconds when it was sent.
webhook-signaturev1, followed by a base64 HMAC-SHA256 signature. May hold several, separated by spaces.

The signature is HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw body}, keyed with your secret (the part after whsec_, base64-decoded).

Verify with the SDK

Always verify before trusting a delivery. You need the raw request body: parsing the JSON and serializing it again changes the bytes and breaks the signature.

app/hooks/whocoming/route.ts
import { verifyWebhook, WebhookVerificationError } from "@whocoming/sdk";

export async function POST(request: Request) {
  const rawBody = await request.text();
  let event;
  try {
    event = await verifyWebhook(rawBody, request.headers, process.env.WHOCOMING_WEBHOOK_SECRET);
  } catch (error) {
    if (error instanceof WebhookVerificationError) return new Response("Bad signature", { status: 400 });
    throw error;
  }

  if (await alreadyHandled(event.id)) return new Response(null, { status: 204 });

  switch (event.type) {
    case "rsvp.created":
      await addToGuestList(event.data);
      break;
    case "rsvp.cancelled":
      await removeFromGuestList(event.data.id);
      break;
    default:
      // New types may be added. Ignore the ones you do not use.
      break;
  }

  await markHandled(event.id);
  return new Response(null, { status: 204 });
}

With a client already set up, await wc.webhooks.verify(rawBody, headers, secret) does the same. Timestamps more than five minutes from your server's clock are refused, to stop replays.

Verify by hand

The signed content is the delivery ID, the timestamp and the raw body joined with dots. The key is the part of your secret after whsec_, base64-decoded.

Node.js
import { createHmac, timingSafeEqual } from "node:crypto";

export function isValid(rawBody: string, headers: Headers, secret: string): boolean {
  const id = headers.get("webhook-id");
  const timestamp = headers.get("webhook-timestamp");
  const signatures = headers.get("webhook-signature");
  if (!id || !timestamp || !signatures) return false;

  // Refuse anything older or newer than five minutes.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = createHmac("sha256", key).update(`${id}.${timestamp}.${rawBody}`).digest();

  return signatures.split(" ").some((entry) => {
    const [version, signature] = entry.split(",");
    if (version !== "v1" || !signature) return false;
    const given = Buffer.from(signature, "base64");
    return given.length === expected.length && timingSafeEqual(given, expected);
  });
}
Python
import base64, hashlib, hmac, time

def is_valid(raw_body: bytes, headers, secret: str) -> bool:
    msg_id = headers["webhook-id"]
    timestamp = headers["webhook-timestamp"]
    if abs(time.time() - int(timestamp)) > 300:
        return False
    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{msg_id}.{timestamp}.".encode() + raw_body
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
    return any(
        hmac.compare_digest(sig, expected)
        for version, _, sig in (entry.partition(",") for entry in headers["webhook-signature"].split(" "))
        if version == "v1"
    )

Any Standard Webhooks library works too.

Delivery and retries

  • At least once. A delivery counts as done when your endpoint answers with any 2xx. Anything else (or no answer within 10 seconds) is retried.
  • Retry schedule. The first retry comes 30 seconds after a failure, and each wait doubles (1 minute, 2, 4, 8 and so on) up to two hours, with a little random spread so endpoints that failed together do not retry together. That is about eight tries in the first two hours, then one every two hours. Retries stop 24 hours after the delivery was created: it is then marked failed and the organization's owners are emailed.
  • Ten failures in a row disable the endpoint. disabled_at is set and nothing more is sent. Fix your handler, then turn it back on with PATCH /v1/webhook-endpoints/{id} and { "disabled": false }, which also resets the count. A single success resets it too.
  • Answer fast. Return 2xx as soon as you have stored the delivery, and do slow work afterwards.

Treat id as an idempotency key

Because delivery is at least once, the same delivery can arrive twice (for example when your server handled it but the answer was lost). Every attempt of one delivery carries the same id and webhook-id. Store the IDs you have handled and skip repeats, as in the example above.

Deliveries are not guaranteed to arrive in order. Use data.updated_at to tell which version of an RSVP is newest.

The delivery log

curl "https://api.whocoming.com/v1/webhook-deliveries?status=failed" \
  -H "Authorization: Bearer wc_test_..."

Each delivery shows its status (pending while retries remain, delivered, failed, or skipped when WhoComing decided not to send it), attempts, next_attempt_at, the last HTTP status and error, and the exact payload sent. Filter by endpoint_id or status.

The log is for looking into recent deliveries, not an archive:

  • After 30 days, the guest's name, email and answers are removed from finished deliveries. The rest of the delivery stays.
  • After 90 days, finished deliveries (delivered, skipped and failed) are deleted. Deliveries still being retried are never deleted.
  • Erasing a guest removes their details from stored deliveries at once.

Keep your own copy of anything you need for longer.

To send one again with the same webhook-id, for example after fixing a bug:

curl -X POST https://api.whocoming.com/v1/webhook-deliveries/dlv_7b2d4f6h8j0l2n4p6r8t/retry \
  -H "Authorization: Bearer wc_test_..."

The same log, with a redeliver button, is in the dashboard.

Testing locally

Your laptop is not reachable from the internet, so expose your local server through a tunnel:

# Cloudflare (free, no account needed for a quick tunnel)
cloudflared tunnel --url http://localhost:3000

# or ngrok
ngrok http 3000
  1. Copy the public https:// URL the tunnel prints.
  2. Register it with a test key: https://<your-tunnel>/hooks/whocoming.
  3. Put the secret from the response in your local environment.
  4. Create a test RSVP (the quickstart cURL works) and watch it arrive.
  5. Changed your handler? Redeliver the same delivery from the log instead of creating new data.

Test-mode deliveries are signed and retried exactly like live ones.

On this page