Skip to content

Events ​

What a business's own systems will hear when something happens on its site: a booking taken, moved or cancelled, money paid, an enquiry sent, a version published. Each is a named, versioned message in one envelope.

Nothing is delivered yet. The platform writes these events down today, in the same transaction as the change each one reports; webhooks, the keys a business makes for its till, and the API that reads the events back come later. This page is the contract they will deliver, fixed now so that what is built on it can rely on the names.

The envelope ​

json
{
  "id": "evt_01JCZ8A0K1M2N3P4Q5R6S7T8V9",
  "type": "booking.moved",
  "v": 1,
  "timestamp": "2026-11-12T10:05:00Z",
  "site": "d6fc4fd9-2c1e-4c52-9a0e-5b7f2f1a8e31",
  "stream": "live",
  "subject": {
    "kind": "booking",
    "id": "0b8e5a1c-6f0e-4d4b-9c1a-2f7d3e8b4c55",
    "seq": 4
  },
  "people": "none",
  "data": {
    "booking": "0b8e5a1c-6f0e-4d4b-9c1a-2f7d3e8b4c55",
    "from": {
      "starts_at": "2026-11-12T13:00:00Z",
      "ends_at": "2026-11-12T13:45:00Z",
      "resource": {
        "slug": "lea",
        "title": "Lea"
      }
    },
    "to": {
      "starts_at": "2026-11-12T15:00:00Z",
      "ends_at": "2026-11-12T15:45:00Z",
      "resource": {
        "slug": "mia",
        "title": "Mia"
      }
    },
    "tz": "Europe/Zurich",
    "by": "customer"
  }
}
  • id is the event's own, evt_ and a ULID, so ids sort by time. It is the same on every retry and to every receiver: keep the ids you have seen for a few days and ignore a repeat.
  • type is noun.verb. v is the version of that type's data.
  • timestamp is when the thing happened, not when it was sent. Times are UTC; a booking's tz is the site's zone.
  • stream is live or test. A test booking is a test event, and a receiver set up for the test stream never hears a live one.
  • subject is what the event is about — a booking, an enquiry, the site — and seq counts that subject's events from 1. Order is not promised; seq makes it recoverable: a receiver that has seen 5 of a booking drops a late 4. A booking's payments are in the booking's story.
  • people is how much of a person this delivery carries: none, names or contacts, as the business set it for the receiver, or gone when the record was forgotten before the event was sent. The default is none: ids and facts. A name, a telephone or an email is sent only where the business turned it on for that receiver, under data.person, so dropping one key drops the person.
  • data is the type's payload, below. Money is amount_minor and currency: ISO minor units, as everywhere on the platform. Ids are opaque strings.

What changes, and what does not ​

A new type, a new field in data, a longer id: not a break, and the same version — ignore what you do not know. A new value in a list of values (a new reason) is announced a month ahead; treat one you do not know as other. A field removed or renamed, or a meaning changed, makes v: 2 of that type, and both are sent side by side for six months.

booking.forgotten is the one event every receiver that heard of a booking gets, at any level: the booking left the platform, so delete what you hold of it. It carries the booking's id and why, and nothing else.

The types ​

typevaboutsent
booking.created1bookingwritten today
booking.confirmed1bookingwritten today
booking.moved1bookingwritten today
booking.cancelled1bookingwritten today
booking.no_show1bookingwritten today
booking.attended1bookingwritten today
booking.forgotten1bookingwritten today
payment.paid1bookingwritten today
payment.refunded1bookingwritten today
payment.unbooked1bookingwritten today
enquiry.received1enquirywritten today
pass.issued1passdefined; its module is not built yet
pass.stamped1passdefined; its module is not built yet
pass.redeemed1passdefined; its module is not built yet
pass.voided1passdefined; its module is not built yet
content.version_saved1sitewritten today
content.published1sitewritten today
site.launched1sitewritten today

Bookings ​

booking.created ​

A booking is taken: by a visitor on the site, or by hand in the diary. Each row of a group is a booking of its own and an event of its own, with the group's id.

fieldkindlevelvalues
bookingstringnone
groupstringnone
serviceobjectnone
service.slugstringnone
service.titlestringnone
serviceslist of objectsnone
services[].slugstringnone
services[].titlestringnone
resourceobjectnone
resource.slugstringnone
resource.titlestringnone
starts_attimenone
ends_attimenone
tzstringnone
partyintegernone
statestringnonepending, confirmed
sourcestringnonesite, manual, api, import
amount_minorintegernone
currencystringnone
paymentstringnoneno, deposit, full
person.namestringnames
person.phonestringcontacts
person.emailstringcontacts
person.notestringcontacts

data, at contacts:

json
{
  "booking": "0b8e5a1c-6f0e-4d4b-9c1a-2f7d3e8b4c55",
  "group": "",
  "service": {
    "slug": "damenschnitt",
    "title": "Damenschnitt"
  },
  "services": [
    {
      "slug": "damenschnitt",
      "title": "Damenschnitt"
    }
  ],
  "resource": {
    "slug": "lea",
    "title": "Lea"
  },
  "starts_at": "2026-11-12T13:00:00Z",
  "ends_at": "2026-11-12T13:45:00Z",
  "tz": "Europe/Zurich",
  "party": 1,
  "state": "pending",
  "source": "site",
  "amount_minor": 8500,
  "currency": "CHF",
  "payment": "full",
  "person": {
    "name": "Erika Muster",
    "phone": "+41 79 000 00 00",
    "email": "erika@example.ch",
    "note": "Bitte nur spitzen"
  }
}

booking.confirmed ​

A pending booking is confirmed: by the business, or by its payment arriving.

fieldkindlevelvalues
bookingstringnone
bystringnonebusiness, payment, api
person.namestringnames
person.phonestringcontacts
person.emailstringcontacts
person.notestringcontacts

data, at contacts:

json
{
  "booking": "0b8e5a1c-6f0e-4d4b-9c1a-2f7d3e8b4c55",
  "by": "payment",
  "person": {
    "name": "Erika Muster",
    "phone": "+41 79 000 00 00",
    "email": "erika@example.ch",
    "note": "Bitte nur spitzen"
  }
}

booking.moved ​

A booking is given another time or another resource: by the customer through their link, or by the business in the diary (an undo is a move back).

fieldkindlevelvalues
bookingstringnone
fromobjectnone
from.starts_attimenone
from.ends_attimenone
from.resourceobjectnone
from.resource.slugstringnone
from.resource.titlestringnone
toobjectnone
to.starts_attimenone
to.ends_attimenone
to.resourceobjectnone
to.resource.slugstringnone
to.resource.titlestringnone
tzstringnone
bystringnonecustomer, business, api
person.namestringnames
person.phonestringcontacts
person.emailstringcontacts
person.notestringcontacts

data, at contacts:

json
{
  "booking": "0b8e5a1c-6f0e-4d4b-9c1a-2f7d3e8b4c55",
  "from": {
    "starts_at": "2026-11-12T13:00:00Z",
    "ends_at": "2026-11-12T13:45:00Z",
    "resource": {
      "slug": "lea",
      "title": "Lea"
    }
  },
  "to": {
    "starts_at": "2026-11-12T15:00:00Z",
    "ends_at": "2026-11-12T15:45:00Z",
    "resource": {
      "slug": "mia",
      "title": "Mia"
    }
  },
  "tz": "Europe/Zurich",
  "by": "customer",
  "person": {
    "name": "Erika Muster",
    "phone": "+41 79 000 00 00",
    "email": "erika@example.ch",
    "note": "Bitte nur spitzen"
  }
}

booking.cancelled ​

A booking stops going ahead: withdrawn by the customer, cancelled or refused by the business, or lapsed when a hold nobody answered or paid ran out.

fieldkindlevelvalues
bookingstringnone
bystringnonecustomer, business, platform, api
reasonstringnonewithdrawn, cancelled, refused, lapsed
refund_duebooleannone
person.namestringnames
person.phonestringcontacts
person.emailstringcontacts
person.notestringcontacts

data, at contacts:

json
{
  "booking": "0b8e5a1c-6f0e-4d4b-9c1a-2f7d3e8b4c55",
  "by": "business",
  "reason": "cancelled",
  "refund_due": true,
  "person": {
    "name": "Erika Muster",
    "phone": "+41 79 000 00 00",
    "email": "erika@example.ch",
    "note": "Bitte nur spitzen"
  }
}

booking.no_show ​

A booking is marked did not come.

fieldkindlevelvalues
bookingstringnone
bystringnonebusiness, api
person.namestringnames

data, at contacts:

json
{
  "booking": "0b8e5a1c-6f0e-4d4b-9c1a-2f7d3e8b4c55",
  "by": "business",
  "person": {
    "name": "Erika Muster"
  }
}

booking.attended ​

A booking is marked came (the state done).

fieldkindlevelvalues
bookingstringnone
bystringnonebusiness, scan, api
attended_attimenone
person.namestringnames

data, at contacts:

json
{
  "booking": "0b8e5a1c-6f0e-4d4b-9c1a-2f7d3e8b4c55",
  "by": "business",
  "attended_at": "2026-11-12T15:46:00Z",
  "person": {
    "name": "Erika Muster"
  }
}

booking.forgotten ​

The booking left the platform: its retention ended, the business's tests were cleared, or a demo went to another studio. Its id and why, and nothing else, ever: a receiver deletes what it holds of it.

fieldkindlevelvalues
bookingstringnone
reasonstringnoneretention, tests_cleared, demo_cleared, erased

No person, at any level.

data, at none:

json
{
  "booking": "0b8e5a1c-6f0e-4d4b-9c1a-2f7d3e8b4c55",
  "reason": "retention"
}

Payments ​

payment.paid ​

Money for a booking arrived. Today that is a card payment through the business's own Stripe account; a payment at the counter and one recorded from another system come with the same type. A group paid at once is one event per booking, each with its share.

fieldkindlevelvalues
paymentstringnone
bookingstringnone
amount_minorintegernone
currencystringnone
methodstringnonestripe, counter, outside
payment_intentstringnone
meansstringnonecash, card, twint, other
receiptstringnone

No person, at any level.

data, at none:

json
{
  "payment": "pi_3QExampleExample0001",
  "booking": "0b8e5a1c-6f0e-4d4b-9c1a-2f7d3e8b4c55",
  "amount_minor": 8500,
  "currency": "CHF",
  "method": "stripe",
  "payment_intent": "pi_3QExampleExample0001",
  "means": "",
  "receipt": ""
}

payment.refunded ​

Money for a booking went back through Stripe, whole or in part.

fieldkindlevelvalues
paymentstringnone
bookingstringnone
refunded_minorintegernone
refunded_total_minorintegernone
currencystringnone

No person, at any level.

data, at none:

json
{
  "payment": "pi_3QExampleExample0001",
  "booking": "0b8e5a1c-6f0e-4d4b-9c1a-2f7d3e8b4c55",
  "refunded_minor": 8500,
  "refunded_total_minor": 8500,
  "currency": "CHF"
}

payment.unbooked ​

Money arrived, and the time could not be kept: the hold had run out and the hour was taken, or the booking had been cancelled. The business has to call the customer back. Follows the booking's payment.paid.

fieldkindlevelvalues
paymentstringnone
bookingstringnone
serviceobjectnone
service.slugstringnone
service.titlestringnone
resourceobjectnone
resource.slugstringnone
resource.titlestringnone
starts_attimenone
amount_minorintegernone
currencystringnone
person.namestringnames
person.phonestringcontacts
person.emailstringcontacts

data, at contacts:

json
{
  "payment": "pi_3QExampleExample0001",
  "booking": "0b8e5a1c-6f0e-4d4b-9c1a-2f7d3e8b4c55",
  "service": {
    "slug": "damenschnitt",
    "title": "Damenschnitt"
  },
  "resource": {
    "slug": "lea",
    "title": "Lea"
  },
  "starts_at": "2026-11-12T13:00:00Z",
  "amount_minor": 8500,
  "currency": "CHF",
  "person": {
    "name": "Erika Muster",
    "phone": "+41 79 000 00 00",
    "email": "erika@example.ch"
  }
}

Enquiries ​

enquiry.received ​

A form on the site is sent.

fieldkindlevelvalues
enquirystringnone
page_pathstringnone
channelstringnone
fieldslist of stringnone
attachmentsintegernone
person.namestringnames
person.phonestringcontacts
person.emailstringcontacts
person.messagestringcontacts
person.fieldsobject of stringcontacts

data, at contacts:

json
{
  "enquiry": "5a0c7e2b-1d3f-4e6a-8b9c-0d1e2f3a4b5c",
  "page_path": "/kontakt",
  "channel": "form",
  "fields": [
    "hair_length",
    "preferred_day"
  ],
  "attachments": 1,
  "person": {
    "name": "Erika Muster",
    "phone": "+41 79 000 00 00",
    "email": "erika@example.ch",
    "message": "Haben Sie am Samstag noch etwas frei?",
    "fields": {
      "hair_length": "lang",
      "preferred_day": "Samstag"
    }
  }
}

Passes ​

pass.issued ​

A customer gets the business's pass (wiki/103). Not sent yet: the passes are not built.

fieldkindlevelvalues
passstringnone
serialstringnone
partslist of stringnonenext_visit, stamps, sessions
routestringnonesite, booking, email, counter
templateintegernone
person.namestringnames
person.phonestringcontacts
person.emailstringcontacts

data, at contacts:

json
{
  "pass": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "serial": "K7QM4F2T",
  "parts": [
    "next_visit",
    "stamps"
  ],
  "route": "booking",
  "template": 1,
  "person": {
    "name": "Erika Muster",
    "phone": "+41 79 000 00 00",
    "email": "erika@example.ch"
  }
}

pass.stamped ​

A stamp is added to a pass or taken back. Not sent yet: the passes are not built.

fieldkindlevelvalues
passstringnone
deltaintegernone
stampsintegernone
goalintegernone
reward_readybooleannone
bystringnonescan, visit, hand, api
person.namestringnames

data, at contacts:

json
{
  "pass": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "delta": 1,
  "stamps": 6,
  "goal": 10,
  "reward_ready": false,
  "by": "scan",
  "person": {
    "name": "Erika Muster"
  }
}

pass.redeemed ​

A pass's reward is redeemed and its count starts again. Not sent yet: the passes are not built.

fieldkindlevelvalues
passstringnone
partstringnonestamps
rewardstringnone
codestringnone
person.namestringnames

data, at contacts:

json
{
  "pass": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "part": "stamps",
  "reward": "free_wash",
  "code": "",
  "person": {
    "name": "Erika Muster"
  }
}

pass.voided ​

A pass ends. Not sent yet: the passes are not built.

fieldkindlevelvalues
passstringnone
reasonstringnoneowner, untouched, erased, replaced

No person, at any level.

data, at none:

json
{
  "pass": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "reason": "owner"
}

Content ​

content.version_saved ​

A version of the site's content is saved: a person's save in the panel, or a branch brought in under the draft.

fieldkindlevelvalues
versionstringnone
bystringnoneowner, admin, staff, studio, agent, platform, import
pagesintegernone
removedintegernone

No person, at any level.

data, at none:

json
{
  "version": "4f2c1d9a7b3e5f60718293a4b5c6d7e8f9012345",
  "by": "owner",
  "pages": 2,
  "removed": 0
}

content.published ​

A version goes live on a launched site: the build the world is shown changes.

fieldkindlevelvalues
versionstringnone
buildstringnone
urlstringnone

No person, at any level.

data, at none:

json
{
  "version": "4f2c1d9a7b3e5f60718293a4b5c6d7e8f9012345",
  "build": "3e9a1f2b-5c6d-4e7f-8a9b-0c1d2e3f4a5b",
  "url": "https://www.salon-muster.ch"
}

The site ​

site.launched ​

The site goes live on its own address for the first time.

fieldkindlevelvalues
domainstringnone
launched_attimenone

No person, at any level.

data, at none:

json
{
  "domain": "www.salon-muster.ch",
  "launched_at": "2026-11-12T06:30:00Z"
}