API & Webhooks

Authentication

Every request to /api/v1 is authenticated with a Bearer API key. Keys are issued in the platform admin backend and shown once at creation — store them securely. Keys can be revoked at any time.

Authorization: Bearer htm_live_xxxxxxxxxxxxxxxx

Errors return JSON with an HTTP status:

{ "error": { "type": "unauthorized", "message": "Invalid or revoked API key." } }

Events

List endpoints return { data, has_more, limit, offset } and accept ?limit (1–200, default 50) and ?offset.

List events. A platform key sees all events; a tenant-scoped key sees only its own.

List an event's guests. Optional ?status= filter (any rsvp_status).

GET /api/v1/events/de67275f-…/guests?status=confirmed&limit=100
Authorization: Bearer htm_live_…

Guests

Retrieve a single guest.

{
  "id": "9f68bce4-…",
  "event_id": "de67275f-…",
  "tenant_id": "eaf46754-…",
  "full_name": "דנה כהן",
  "phone_e164": "+972545283882",
  "locale": "he",
  "rsvp_status": "rsvp_sent",
  "payment_status": "none",
  "seats": 2,
  "created_at": "2026-07-12T09:00:00.000Z"
}

rsvp_status: imported, rsvp_sent, confirmed, declined, no_response.  payment_status: none, link_sent, partial, paid.

Report an RSVP outcome

The AI-calling engine writes back a call result. Returns the updated guest and emits the matching webhook.

POST /api/v1/guests/9f68bce4-…/rsvp
Authorization: Bearer htm_live_…
Content-Type: application/json

{ "status": "confirmed", "seats": 3 }

• status — one of confirmed, declined, no_response (required)
• seats — integer ≥ 0, applied when status = confirmed (optional)

Webhooks

Register endpoint URLs in the admin backend and subscribe to event types. We POST a signed JSON envelope to each subscribed endpoint when an event occurs.

{
  "id": "evt_2b1f…",
  "type": "guest.rsvp_confirmed",
  "created": 1752316800,
  "data": { "object": { /* guest object */ } }
}

Verifying signatures

Each request carries:

Hatumoney-Signature: t=<unix_seconds>,v1=<hex_hmac_sha256>
Hatumoney-Event: guest.rsvp_confirmed

v1 is HMAC-SHA256(secret, "<t>.<raw_body>") using the endpoint's signing secret. Recompute and compare, and reject requests whose t is older than a few minutes to prevent replay.

import crypto from "crypto";

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(parts.v1),
  );
}

Delivery & retries

Delivery is asynchronous (typically within ~1 minute). A non-2xx response or timeout is retried with exponential backoff (~1m, 5m, 30m, 2h, 6h) up to 6 attempts. Endpoints should be idempotent — dedupe on the event id — and respond 2xx quickly.