IHGIZ · Developers

IHGIZ Event Engine

One Event, defined once, for every IHGIZ template. Version 0.1.0, at https://ihgiz.net/api/engine/v0. Every call carries a tenant API key, made in the console, with the scopes it needs.

Events

Read and create Events.

  • GET/eventsList Events

    Events of the caller's tenant, newest start first, filtered by template, type, phase, time window or person.

    Needs: events:read

  • POST/eventsCreate an Event

    Creates an Event in its graph's initial state, or runs one named transition from it in the same call (for instance a booking that confirms itself). The history records who created it.

    Needs: events:write

  • GET/events/{uid}Get an Event

    Needs: events:read

Transitions

The one way an Event changes.

  • GET/events/{uid}/transitionsTransitions the caller may fire now

    The transitions of the Event's graph that start from its current state and that the caller's actor kind may fire, with guards evaluated. Consoles render only these.

    Needs: events:read

  • POST/events/{uid}/transitionsChange an Event

    The one write path. Applies a named transition from the template's graph, with the changes it allows (new time, place, people), and returns the Event as it now stands with the history entry, the messages and the iTIP method it raised. Refused with 422 and the name of the guard that said no; with 412 when If-Match is not the current sequence.

    Needs: events:transition

  • GET/events/{uid}/historyEverything that happened to an Event

    Append-only, oldest first. Answers "who changed this, from what, to what, and why" from the record alone.

    Needs: events:read

Participants

Answers from the people taking part.

  • POST/events/{uid}/participants/{participantId}/replyA participant answers

    A participant accepts, declines or answers tentatively, optionally proposing a new time (iTIP COUNTER). This is the reply transition of the Event's graph, fired as that participant; it is authorised by the participant's own reply token, so a guest needs no account.

    Needs: replyTokenevents:transition

Calendar

iCalendar views of an Event.

  • GET/events/{uid}/calendarThe Event as an iCalendar file

    RFC 5545 VCALENDAR with one VEVENT (or the series), with the iTIP method requested. The same UID and SEQUENCE as every message about the Event.

    Needs: events:readreplyToken

Templates

What each template declares.

  • GET/templatesTemplates switched on for the tenant

    Needs: templates:read

  • GET/templates/{templateId}A template's manifest

    The manifest as data — names, roles, event types, entities and state graphs — valid against /schemas/template-manifest.schema.json.

    Needs: templates:read

Entities

Things that are not Events but have a lifecycle — a membership, a deal, an order.

  • GET/entitiesA page of the tenant's entities, newest first

    Needs: entities:read

  • POST/entitiesCreate an entity in its graph's initial state

    Needs: entities:write

  • GET/entities/{uid}An entity, with where it stands in each region

    Needs: entities:read

  • GET/entities/{uid}/transitionsWhat the caller may do to the entity now, region by region

    Needs: entities:read

  • POST/entities/{uid}/transitionsMove the entity by a named transition

    Needs: entities:write

  • GET/entities/{uid}/historyEvery change to the entity, oldest first

    Needs: entities:read

Webhooks

Where the engine posts each change (asyncapi.yaml).

  • GET/webhooksThe tenant's webhook endpoints

    Needs: webhooks:manage

  • POST/webhooksAdd an endpoint

    The response carries the endpoint's signing secret, the only time it is shown. The URL must be https and reach a public address — checked now and again at every delivery.

    Needs: webhooks:manage

  • DELETE/webhooks/{webhookId}Remove an endpoint

    Deliveries still queued for it stop.

    Needs: webhooks:manage

Webhook messages

CloudEvents 1.0, posted to each endpoint a tenant registers and signed with its secret: x-ihgiz-signature is the hex HMAC-SHA256 of ${x-ihgiz-timestamp}.${body}.

  • net.ihgiz.event.created — An Event was created, in its graph's initial state or after the transition run with it.
  • net.ihgiz.event.transitioned — A transition applied — a new time, place or people, or a new state.
  • net.ihgiz.event.participant.replied — A participant accepted, declined, answered tentatively or proposed a new time.
  • net.ihgiz.event.cancelled — The Event reached the cancelled phase (iTIP CANCEL).
  • net.ihgiz.entity.created — A membership, a deal, an order — something with a lifecycle that is not an Event — was created.
  • net.ihgiz.entity.changed — An entity moved by a named transition, in one region of its graph.