# Event Log

An **Event Log** is a read-only system entry that acts as the source ledger for all loyalty occurrences on the Gamopanda platform. Each time a member's progress changes (e.g. they complete a streak, hit a milestone, fail a challenge, or trigger warning thresholds), the platform logs an Event Log entry. These logs form the foundation of outgoing [Webhooks](/webhook) and [Email Notifications](/email-notification).

:::info
Event Logs are strictly **read-only** (`GET`, `LIST`) audit records generated by the system. They cannot be created, modified, or deleted by administrators.
:::

---

## How it works

1. **State changes** — a member logs activity or a period boundary lapses (e.g., a streak period ends), causing a state shift.
2. **Log entry generated** — the system records an `Event Log` entry containing the event category (`eventCode`) and the complete context data (`payload`). The status starts as `not_processed`.
3. **Trigger evaluation** — the platform processes the log and looks for matching [Webhooks](/webhook) or [Email Notifications](/email-notification) configured to run for that `eventCode`.
4. **Transition to processed** — once the platform evaluates all rules and queues outgoing callbacks or emails, the log transitions to `processed`.

---

## Fields

### Audit information

| Field | Type | Description |
|---|---|---|
| `eventCode` | enum | The type of event that occurred. See [Event Codes](/webhook#event-codes) for the complete list. |
| `payload` | object | Raw JSON payload containing contextual objects (e.g., Member, Streak, Challenge Progress) associated with the event. |

### Status

| Field | Type | Default | Description |
|---|---|---|---|
| `logStatus` | enum | `not_processed` | Processing status: `not_processed` · `processed` |
| `status` | enum | `live` | Log visibility status: `draft` · `live` · `paused` |

---

## Event codes

The `eventCode` defines the type of loyalty event that occurred:

- `streak_progress_broken`
- `streak_progress_to_be_broken`
- `streak_progress_completed`
- `streak_progress_milestone_completed`
- `streak_progress_non_milestone_completed`
- `streak_progress_in_progress`
- `challenge_progress_failed`
- `challenge_progress_to_be_failed`
- `challenge_progress_completed`
- `challenge_progress_milestone_completed`
- `challenge_progress_in_progress`

---

### Event Log payload
| Variable | Description | Example value |
|---|---|---|
|streakLog| Streak log object (When `eventCode` is one of `streak_progress_completed`, `streak_progress_milestone_completed`, `streak_progress_non_milestone_completed`, `streak_progress_in_progress`  ) | Refer this [Streak Log](/streak-log) for object details|
|challengeLog| Challenge log object (When `eventCode` is one of `challenge_progress_completed`, `challenge_progress_milestone_completed`, `challenge_progress_in_progress`) | Refer this [Challenge Log](/challenge-log) for object details|
|streakProgress| Streak progress object (When `eventCode` is one of `streak_progress_broken`, `streak_progress_to_be_broken`) | Refer below for the object structure |
|challengeProgress| Challenge progress object (When `eventCode` is one of `challenge_progress_failed`, `challenge_progress_to_be_failed`) | Refer below for the object structure |

**$event_log.payload.streakProgress**
```json
{
  ...<Streak Progress>,
  "streak": <Streak>,
  "nextMilestone": <Milestone> | null
}
```
Refer this [Streak Progress](/streak-progress) for object details

Refer this [Streak](/streak) for object details

Refer this [Milestone](/milestone) for object details

**$event_log.payload.challengeProgress**
```json
{
  ...<Challenge Progress Object>,
  "challenge": <Streak Object>,
  "nextMilestone": <Milestone Object> | null
}
```
Refer this [Challenge Progress](/challenge-progress) for object details

Refer this [Challenge](/challenge) for object details

Refer this [Milestone](/milestone) for object details

---

## Real-world examples

**🔍 Reading an Event Log Entry**

An audit log showing a member completing their daily streak progress, ready to trigger email notifications or webhooks:

```json
{
  "id": "019985db-c631-74b1-913d-b404a5640c8c",
  "createdAt": "2026-07-14T08:00:00.000Z",
  "updatedAt": "2026-07-14T08:00:01.000Z",
  "eventCode": "streak_progress_completed",
  "payload": {
    "streakLog": {
      "streakId": "019985db-c631-74b1-913d-b404a5640c8c",
      ...
    },
  },
  "logStatus": "processed",
  "status": "live"
}
```

---

## Access & permissions

| Caller | Allowed operations | Notes |
|---|---|---|
| Admin | GET · LIST | Read-only ledger records |
| End user | *(none)* | No access |
| Guest user | *(none)* | No access |

---

## Related resources

| Resource | Description |
|---|---|
| [Webhook](/webhook) | Outgoing callbacks triggered by event codes |
| [Email Notification](/email-notification) | Outgoing email alerts triggered by event codes |
| [Webhook Log](/webhook-log) | Delivery attempts log for callbacks initiated by these event logs |
| [Email Notification Log](/email-notification-log) | Delivery attempts log for emails initiated by these event logs |

---

## API reference

See the [API Reference](/api/event_log) for full request/response schemas and interactive examples for:

- `GET /schema/event_log/record` — list event logs
- `GET /schema/event_log/record/{id}` — get an event log by ID