Website & booking-engine events

Overview

A booking engine knows the moment a guest leaves; a hotel wants to write to that guest while the trip is still on their mind. Events connect the two. Something on your website or booking engine sends an event, the guest is matched to a contact, and a journey whose trigger is that event starts.

  YOUR SIDE                                  GUESTMAKER

  Server API   POST /api/v1/website-events  --+
  Webhook      POST .../hooks/gme_wh_...    --+-->  one contract  -->  contact + consent evidence
  Browser SDK  gm-events.js                 --+                   |
                                                                  +->  journey trigger --> wait --> email / WhatsApp
                                                                                      |
                                                                                      +--> stops when the booking completes

There is nothing to register first. Send an event with any valid name and it appears in the journey editor's dropdown as soon as it has been received, next to the standard events below. Each source (one system that sends events) gets its own key, so you can pause or replace one without touching the others.

Quickstart

1. In GuestMaker open Settings → Integrations → Website & booking-engine events, choose New source, pick Server and copy the secret key. It is shown once.
2. Send your first event. Add "test": true so it is checked and logged without touching any guest.
3. Open the source's Delivery log: the event is there with its result. Fix anything it flags.
4. In a journey, choose the trigger Website or booking-engine event, pick Cart abandoned, add a Wait and an email, and activate.

curl -X POST 'https://www.guestmaker.ai/api/v1/website-events' \
  -H 'Authorization: Bearer gme_sk_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"event":"cart.abandoned","idempotency_key":"cart_8841","contact":{"email":"ana@example.com","first_name":"Ana","language":"es"},"consent":{"email_marketing":true,"text":"I agree to receive offers from this hotel by email","captured_at":"2026-09-30T10:11:58Z","language":"en","form_id":"checkout-details"},"context":{"hotel_code":"HD-MAD","stage":"payment","check_in":"2026-11-20","check_out":"2026-11-23","adults":2,"room_name":"Deluxe","value":612.4,"currency":"EUR","cart_id":"8841","resume_url":"https://book.example.com/resume?cart=8841"}}'

A successful request answers 202 with a result per event. The example above is a real abandoned cart including consent evidence; add "test": true to try it safely.

{
  "received": 1,
  "accepted": 1,
  "duplicate": 0,
  "rejected": 0,
  "results": [
    {
      "index": 0,
      "status": "accepted",
      "code": "accepted",
      "message": "Accepted",
      "event_id": "9b0e…",
      "contact": "matched",
      "warnings": []
    }
  ]
}

Choose a door

All three doors accept the same events and apply the same rules. Pick by what your side can do.

The event

* marks a required field. Everything else is optional, and a field the contract does not list is refused rather than ignored.

Standard events

These have their own place at the top of the journey editor's dropdown. Any other name that is lowercase and dotted (for example custom.spa_viewed) is a custom event: send it and it becomes selectable once received.

On cart.abandoned, context.stage says where the guest left: dates, room, extras, details, payment. A journey can be limited to some stages, for example only guests who reached payment.

Server API

POST /api/v1/website-events with Authorization: Bearer gme_sk_… and a JSON body: one event, or { "events": [ … ] } with up to 50. In a batch every event is judged on its own: the request succeeds and each event carries its own result, so one bad event does not reject the others.

Idempotency and retries

Give each event an idempotency_key. Sending the same key again is answered duplicate and changes nothing, so retry freely. (An event that no active journey is waiting for is counted but not stored, so a repeat of it is answered accepted again: nothing happens either time.) Retry on 429 (wait Retry-After seconds) and on 5xx; any other 4xx will not succeed with the same bytes.

A single event that fails validation

is answered 422 with results[0].issues naming each field and the problem. The same event inside a batch is reported inside a 202.

{
  "received": 1,
  "accepted": 0,
  "duplicate": 0,
  "rejected": 1,
  "results": [
    {
      "index": 0,
      "status": "rejected",
      "code": "invalid_event",
      "message": "The event does not match the contract",
      "event_id": null,
      "contact": "none",
      "warnings": [],
      "issues": [
        {
          "field": "context.check_out",
          "message": "check_out must be after check_in"
        }
      ]
    }
  ]
}

The full event

{
  "event": "cart.abandoned",
  "idempotency_key": "cart_8841",
  "contact": {
    "email": "ana@example.com",
    "first_name": "Ana",
    "language": "es"
  },
  "consent": {
    "email_marketing": true,
    "text": "I agree to receive offers from this hotel by email",
    "captured_at": "2026-09-30T10:11:58Z",
    "language": "en",
    "form_id": "checkout-details"
  },
  "context": {
    "hotel_code": "HD-MAD",
    "stage": "payment",
    "check_in": "2026-11-20",
    "check_out": "2026-11-23",
    "adults": 2,
    "room_name": "Deluxe",
    "value": 612.4,
    "currency": "EUR",
    "cart_id": "8841",
    "resume_url": "https://book.example.com/resume?cart=8841"
  }
}

The machine-readable description is the OpenAPI document, generated from the same definitions the API validates with, so it cannot drift from what the server accepts.

Webhook and field mapping

Many booking engines can only post their own JSON to a URL. Create a Webhook source, give the engine the private URL, and tell GuestMaker once how the engine's fields map onto ours. No code on either side.

POST https://www.guestmaker.ai/api/v1/website-events/hooks/gme_wh_…?test=1
Content-Type: application/json

{
  "type": "CartAbandoned",
  "step": "PAYMENT",
  "user": {
    "mail": "ana@example.com",
    "name": "Ana"
  },
  "cart": {
    "id": 8841,
    "total": "612,40",
    "currency": "eur"
  },
  "stay": {
    "in": "20/11/2026",
    "out": "23/11/2026"
  }
}

The mapping editor

In the source's Set up field mapping, GuestMaker opens on the newest request the engine actually sent (personal details in it are masked), lists that request's own fields to choose from, and previews the resulting event exactly as the server will build it. Each row takes a value from a field in the payload, a fixed value, or a template such as cart_{{cart.id}}. Transforms available: lower, upper, trim, number, boolean, date, datetime. A word map translates the engine's vocabulary, for example CartAbandoned → cart.abandoned.

Checking the URL

Many booking engines and webhook tools check a URL with a GET before they will save it. A GET on the webhook URL takes no event: it answers 200 with { "ready": true, "signature_required": … } when a POST would be accepted, and otherwise the same 401 or 403 a POST would get, so a paused source is told apart from a mistyped token.

Signing

If the engine can sign its requests, set a signing secret on the source and every request must carry X-GM-Signature: t=<unix seconds>,v1=<hex>, where v1 is the HMAC-SHA256 of "<t>.<raw body>" under the secret, the construction Stripe uses. Sign the exact bytes you send, and use a timestamp within 5 minutes of the server's clock. While you rotate a secret you may send two v1 values.

import { createHmac } from 'node:crypto'

const t = Math.floor(Date.now() / 1000)
const v1 = createHmac('sha256', SIGNING_SECRET).update(`${t}.${rawBody}`).digest('hex')

// rawBody is the EXACT string you send. Then add this header to the request:
const signature = `t=${t},v1=${v1}`   // X-GM-Signature: t=1767225600,v1=5257a869…

Without a secret the private URL is the credential: share it only with the engine, and revoke it from the source if it leaks.

Browser SDK

/sdk/gm-events.js is a small dependency-free script (under 6 KB compressed) that sets no cookies. It sends events from the visitor's browser, and is the only door that sees a guest close the tab, which is exactly when an abandoned cart is decided.

<script async src="https://www.guestmaker.ai/sdk/gm-events.js"></script>
<script>
  window.gme = window.gme || function () { (gme.q = gme.q || []).push(arguments) }
  gme('init', { key: 'gme_pk_YOUR_PUBLIC_KEY' /* , hotelCode: 'HD-MAD' */ })

  // The moment the guest gives an email or phone in your booking form:
  // gme('identify', { email: 'ana@example.com' })

  // Report the booking when the guest leaves without finishing it:
  gme('abandonOnLeave', {
    getCart: function () {
      // Return the booking in progress, or null when there is none.
      return { cart_id: 'YOUR-CART-ID', stage: 'payment', check_in: '2026-11-20', check_out: '2026-11-23', value: 612.4, currency: 'EUR' }
    }
  })

  // When the booking is paid:
  // gme('completed', { cart_id: 'YOUR-CART-ID' })
</script>

Consent ticks

identify(contact, { consent: { email_marketing: true, text, form_id } }) records a consent claim with the sentence you pass and the time of the tick. Without text the tick is sent but ignored by the server, so marketing email will not send.

Google Tag Manager

Paste the Browser SDK snippet above into a Custom HTML tag that fires on your booking pages. Keep the cart in a global variable your site sets, and call gme('identify', …) and gme('completed', …) from further tags.

What it does when things go wrong

It never throws into your page and never blocks it. A network error, 429 or 5xx is retried with backoff (1, 2, 4, 8 seconds) up to five times and honours Retry-After; a 4xx is reported once in the console with the server's reason and not retried. Events tracked while a retry waits queue behind it, so order is kept. At most 50 events wait at once; beyond that the oldest is dropped.

Consent and compliance

These are rules of the platform, not options, and they are the same on every door.

1. No consent evidence, no marketing email. A guest created from an abandoned cart is still created and still starts the journey, but an email step is skipped, with a reason the tenant can see, unless the contact has marketing consent.
2. Consent is evidence or it is ignored. consent.email_marketing: true is honoured only with the exact text the guest agreed to and a captured_at within 7 days. GuestMaker records the sentence, the time, the language, the form and the request's IP and user agent in the consent audit log.
3. An event can never re-subscribe a guest who opted out. If the contact has unsubscribed or is suppressed, a consent claim is ignored and the response says so (consent_ignored_opted_out). A buggy pre-ticked box cannot undo an unsubscribe.
4. Never transactional. A reminder to a guest who left a booking half-finished is a commercial message. Journeys started by a website event send email in the marketing category, and every WhatsApp template they send requires marketing consent, whatever category the template was registered under.
5. Only people. An agency desk, a placeholder or a role account is refused as a person, so an OTA relay address never becomes a marketing contact.

Use it in a journey

Choose the trigger Website or booking-engine event (category Website & Booking Engine). The event dropdown lists the standard events first, then every custom event your account has received, marked “not received yet” until one arrives.

A typical abandoned-cart flow: trigger on cart.abandoned (or checkout.started), Wait 30 minutes, send the reminder email with a button to the guest's resume link. If the guest completes the booking meanwhile, checkout.completed for the same cart ends the journey before the email goes out.

Reading the event in a message

The event's details can be used in the email a journey sends, as merge tags, and in a WhatsApp template as variables. Both read the event that started that journey run.

Email merge tags

Type the tag in the email, or pick it from Website event in the merge-tag picker. Dates are written in the guest's own language (“20 de noviembre de 2026” for a Spanish-speaking guest) and money in their currency style. A value the event did not carry renders as empty text, so give the copy around it a version that reads well without it.

Declare your own events in advance

A custom event normally appears in the trigger's dropdown once your website has sent one. To build the journey before the integration is finished, declare it in Settings → Integrations → Website events → Events you can start a journey from. It is listed as “not received yet”, and the first real event simply counts against it. A declared event nothing has sent can be removed; one that has been received stays in your history. Names use lowercase letters, digits and underscores with dots between parts, and must match what your website sends.

WhatsApp variables

Events are only stored when a guest is identified and an active journey is listening for them, so sending an event nobody waits for costs nothing and creates nothing.

Errors and results

Request-level errors answer with { error: { code, message, detail?, fix, docs } } and the HTTP status shown. The docs link points at the entry below, and fix says what to change.

Limits

Testing

• Add "test": true (or ?test=1 on a webhook URL): the event is validated and logged, and no journey starts and no contact is written.
• Send test event on a source sends one from the dashboard, so you can check the connection before your engine is ready.
• The Delivery log shows every request with its result, the reason it was refused and a link to how to fix it. Personal details in it are masked.
• A request with a missing or wrong key cannot be tied to any source, so it appears in nobody's delivery log: the sender sees the 401, the tenant sees nothing. If a vendor says events are not arriving, start by checking the key with a "test": true request.
• A browser source: add debug: true to init to see what the SDK sends in the console.

Booking-engine vendors

If you are a booking-engine vendor, you do not need an integration with us: your customer creates a Webhook source, maps your fields once, and you post to their URL. This message is what a hotel can send you.

Subject: Send booking events to GuestMaker

Hello,

We use GuestMaker to follow up with guests who leave a booking half-finished. Please send these events
from our booking engine to the webhook URL below, as JSON over HTTPS (POST):

  1. CartAbandoned  – the guest left before paying (please include which step they were on)
  2. BookingPaid    – the guest completed the booking (so we stop following up)

Webhook URL:   https://www.guestmaker.ai/api/v1/website-events/hooks/gme_wh_YOUR_WEBHOOK_TOKEN
Signing:       optional. If you can sign requests, we will give you a secret; the header is
               X-GM-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">

Each payload should carry, in your own field names (we map them, you do not need to change anything):
  - the guest's email (and phone if you have it)
  - the cart or booking id
  - the hotel
  - check-in and check-out dates, adults, room name, total and currency
  - the step reached, and a link that resumes the booking
  - if you collect marketing consent: the exact sentence shown and when it was ticked

An example of what you might send:

{
  "type": "CartAbandoned",
  "step": "PAYMENT",
  "user": {
    "mail": "ana@example.com",
    "name": "Ana"
  },
  "cart": {
    "id": 8841,
    "total": "612,40",
    "currency": "eur"
  },
  "stay": {
    "in": "20/11/2026",
    "out": "23/11/2026"
  }
}

If your tool checks a URL before saving it, a GET on the URL answers 200 when it is live.
Please add "?test=1" to the URL for a first request: it is checked and logged but starts nothing.
Questions: developers@guestmaker.ai

Thank you.

Changelog