Webhooks & REST API

HiLucy exposes a comprehensive REST API under the hilucy/v1 namespace. This API powers both the frontend applications and third-party integrations. If you are building custom integrations or connecting external systems, this guide covers the key endpoint groups, authentication methods, and webhook patterns.

API Endpoint Groups

The API is organized into functional groups, each handling a specific domain:

Service Requests & Operations

The largest endpoint group handles day-to-day property operations -- service requests, contacts, listings, bookings, clients, and inventory management. Over 30 routes cover CRUD operations for all operational data.

Arrivals

Endpoints for the guest check-in flow: token resolution, reservation matching, guest updates, and the idempotent arrive action that transitions a reservation to in-house status.

Reservation Guests

Guest CRUD within a reservation, companion invite and claim workflows, and terms signing endpoints. These power the online check-in and companion claim flows.

Payment & Financial

• Payment Authority -- Multi-payer setup: create setup intents, confirm payment methods, revoke authorities, and bootstrap folios per payer
• Financial -- Ledger queries, balance lookups, commission rule management, and financial reports

Chat

Server-Sent Events (SSE) streaming endpoint that proxies conversations to the LucyAI assistant. Used by the guest portal chat interface for real-time AI responses.

Authentication

Social login (Google, Apple), JWT token refresh, magic link generation, and magic link verification. See the Authentication section below for details.

Connectors & Payouts

Unified integration endpoints for managing third-party connections, plus payout generation, approval, and processing workflows for property owner disbursements.

WiFi Portal

Captive portal endpoints for guest WiFi: session management, guest identification, authorization, and device tracking.

Webhooks (Inbound)

HiLucy receives webhooks from several external services:

• Cloudbeds -- Reservation create/update/cancel events that sync bookings into HiLucy
• Stripe -- Payment confirmations, disputes, and payout events
• Acuity Scheduling -- Appointment bookings and cancellations
• WhatsApp (Meta) -- Message delivery status updates
• Monday.com -- Task creation and status change events

Each inbound webhook endpoint validates the request signature before processing.

Authentication

The API supports multiple authentication modes depending on the endpoint:

• JWT Bearer Token -- Primary method for authenticated requests. Obtain a token via the auth endpoints (social login or magic link), then include it as Authorization: Bearer <token> on subsequent requests.
• Arrival Session Token -- Token-based auth for the check-in flow. No user account required; the token itself grants scoped access to a specific reservation.
• WordPress Session -- Standard WordPress cookie auth for admin-context requests from the dashboard.
• Public -- Some endpoints (such as WiFi portal identification) are publicly accessible without authentication.

Webhook Integration Patterns

If you are building a system that sends webhooks to HiLucy or consumes data from HiLucy events:

• Inbound webhooks are configured per integration in Settings > Integrations. Each integration provides its webhook URL and any required secret keys.
• Idempotency -- Key endpoints (like the arrive action) are idempotent, meaning duplicate webhook deliveries will not create duplicate state changes.
• Signature validation -- All inbound webhooks are verified using HMAC signatures or platform-specific validation (e.g., Stripe webhook signatures, Meta verification tokens).

Rate Limits and Best Practices

• Authenticated endpoints are rate-limited per user token. Avoid polling; use webhooks for real-time updates where possible.
• Always include proper error handling for 401 (token expired), 403 (insufficient permissions), and 429 (rate limit exceeded) responses.
• For bulk operations, batch requests where the API supports it rather than making individual calls per record.

Tips

• Use the JWT refresh endpoint to renew tokens before they expire rather than re-authenticating from scratch
• Test webhook integrations against the dev environment (dev.hilucy.com) before pointing them at production
• Check the integration status indicators in Settings if webhook events appear to stop arriving