Configure endpoints under Settings → Webhooks in the Foyer app. Foyer POSTs a JSON body to the URL you register.
Destination restrictions
Webhook URLs are validated when they are saved and again on every delivery, and the destination is resolved to guard against DNS rebinding. Private, loopback and link-local addresses are rejected — a webhook cannot be pointed at internal infrastructure.
Events
Five event types: message.received, message.sent, message.failed, stay.checked_in and stay.checked_out. Each delivery carries the headers x-foyer-event-id, x-foyer-event-type and x-foyer-signature. x-foyer-event-id identifies the event, not the attempt: it stays the same across every retry, so use it to deduplicate.
stay.checked_in carries data: { stayId }. It fires once per stay, when the guest first opens the door with their personal guest code on or after the arrival day. Walk-ins, bookings created as already checked in, and status changes made through the API or an AI tool do not send it.
stay.checked_out carries data: { stayId }. It fires when a stay is checked out by staff, through the API or an AI tool, or automatically within about 75 minutes after the departure time (the following day for bookings that carry only a departure date, or while a late checkout is offered but not yet paid) — but only if the stay was checked in or the guest opened the door; a stay nobody arrived for is never checked out automatically. It is sent at most once per checkout and not retried if it cannot be queued. A departure the guest reports by message checks the stay out without sending it.
Verifying deliveries
x-foyer-signature has the form t=<unix seconds>,v1=<hex>. v1 is the HMAC-SHA256 of the string "<t>.<raw body>", keyed with the endpoint's signing secret (whsec_…). Compute it over the raw request body, compare in constant time, and reject a timestamp older than five minutes to prevent replays.
import { createHmac, timingSafeEqual } from "node:crypto";
function verify(header: string, rawBody: string, secret: string): boolean {
const t = /(?:^|,)t=(\d+)/.exec(header)?.[1];
const v1 = /(?:^|,)v1=([0-9a-f]+)/.exec(header)?.[1];
if (!t || !v1) return false;
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
const a = Buffer.from(expected, "hex");
const b = Buffer.from(v1, "hex");
return a.length === b.length && timingSafeEqual(a, b);
}Retries
Answer with any 2xx status to acknowledge. Otherwise Foyer retries — at most five attempts in total, after 1 minute, 5 minutes, 30 minutes and 2 hours — and then marks the delivery failed. Delivery is at-least-once: if your 2xx is lost, the same event arrives again with the same x-foyer-event-id and a fresh signature timestamp.