# 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

```graphql
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

```json
{
  "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

```json
{
  "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"
    }
  }
}
```