Create user event

GraphQL endpoint: /user

Records an event about the calling user in their event ledger, on behalf of a partner application.

The partner's backend, authenticated as its company, first mints an event_token for the user with POST /auth/user-event-token; its frontend then calls this mutation with the user's own session and that token. The token is valid for an hour and for any number of requests by that user.

Every event has a fixed envelope — type, externalRef and occurredAt — and a free-form JSON object payload whose shape is defined by the type. type must start with the prefix TNID granted the company (e.g. hoozit.); the event is always about, and recorded by, the calling user.

Posting the same externalRef again returns the event already recorded under it, unchanged. The ledger is append-only: events cannot be changed or deleted, and a correction is recorded as a new event.

Query

mutation (
  $eventToken: String!
  $type: String!
  $externalRef: String!
  $occurredAt: DateTime!
  $payload: JSON!
  $subjectUserId: ID
) {
  createUserEvent(
    eventToken: $eventToken
    type: $type
    externalRef: $externalRef
    occurredAt: $occurredAt
    payload: $payload
    subjectUserId: $subjectUserId
  ) {
    id
    type
    payload
    externalRef
    occurredAt
    recordedAt
    subjectUserId
    actorUserId
  }
}

Variables

{
  "eventToken": "eyJERAMPLE.PAYLOAD1.SIGNATURE",
  "externalRef": "order-1001",
  "occurredAt": "2026-01-15T09:00:01Z",
  "payload": {
    "orderId": "1001",
    "total": {
      "amount": 2599,
      "currency": "USD"
    }
  },
  "type": "hoozit.order.completed"
}

Response

{
  "data": {
    "createUserEvent": {
      "actorUserId": "00000000-0000-4000-8000-000000000001",
      "externalRef": "order-1001",
      "id": "00000000-0000-4000-8000-000000000002",
      "occurredAt": "2026-01-15T09:00:00.000000Z",
      "payload": {
        "orderId": "1001",
        "total": {
          "amount": 2599,
          "currency": "USD"
        }
      },
      "recordedAt": "2026-01-15T09:00:02.000000",
      "subjectUserId": "00000000-0000-4000-8000-000000000001",
      "type": "hoozit.order.completed"
    }
  }
}