# Event-type reference

Every event lands in the per-tenant event log and (if matching) gets fanned out to any subscribed webhook endpoint. The catalog grows over time; this page is the canonical list of what fires today.

## Event envelope

```json
{
  "id":        "evt_01j0wnp3a2…",        // ULID-style, sortable
  "type":      "post.created",            // public type (this catalog)
  "created_at":"2026-05-29T13:42:11.812Z",
  "data":      { /* per-type shape */ }
}
```

## Catalog

| Type                          | Fires when                                                                 |
|-------------------------------|-----------------------------------------------------------------------------|
| `post.created`                | A new thread OP or reply is posted.                                         |
| `post.edited`                 | A post is edited.                                                           |
| `post.deleted`                | A post is soft-deleted.                                                     |
| `user.joined`                 | A user completes registration.                                              |
| `user.left`                   | A user schedules account deletion.                                          |
| `listing.created`             | A marketplace listing goes live. *(2026-05-29)*                             |
| `listing.updated`             | A marketplace listing is edited. *(2026-05-29)*                             |
| `listing.sold`                | A listing's final unit sells out. *(2026-05-29)*                            |
| `listing.withdrawn`           | A listing is withdrawn by owner or moderator. *(2026-05-29)*                |
| `file.uploaded`               | A file upload completes quarantine and is recorded. *(2026-05-29)*          |
| `report.created`              | A user submits a moderation report. *(2026-05-29)*                          |
| `report.resolved`             | A report is resolved (via UI or `POST /api/v1/reports/{id}/resolve`).       |
| `moderation.action_taken`     | A moderator acts on a report. The `data.action` field tells you which action: `warn`, `suspend`, `ban`, `shadow_ban`, or `dismiss`. *(2026-05-29)* |
| `moderation.user_banned`      | Legacy alias for `moderation.action_taken` with `action="ban"`. Will be deprecated. |
| `moderation.user_shadow_banned` | Legacy alias. Will be deprecated. |
| `moderation.user_suspended`   | Legacy alias. Will be deprecated. |
| `moderation.user_warned`      | Legacy alias. Will be deprecated. |
| `moderation.content_removed`  | A moderator removes flagged content.                                        |
| `moderation.content_flagged`  | Content is reported for moderation.                                         |

## New event-data shapes (2026-05-29)

### `listing.created`
```json
{
  "listing_id": 42, "slug": "atari-2600-light-sixer",
  "title": "Atari 2600 Light Sixer", "price_cents": 12500,
  "category_id": 7,
  "seller": { "id": 312, "username": "retroseller" }
}
```

### `listing.sold`
```json
{ "listing_id": 42, "slug": "atari-2600-light-sixer", "seller_id": 312 }
```

### `file.uploaded`
```json
{
  "file_id": 18, "area_slug": "atari-2600-disks",
  "title": "Centipede (1981)", "size_bytes": 16384,
  "mime": "application/octet-stream",
  "uploader": { "id": 312, "username": "retroseller" }
}
```

### `report.created`
```json
{
  "report_id": 91, "reporter": { "id": 7 },
  "reported_user_id": 312, "reported_post_id": 4501,
  "reason_category": "spam", "source_url": "/thread/foo"
}
```

### `moderation.action_taken`
```json
{
  "action": "suspend",
  "target_user_id": 312, "report_id": 91,
  "duration_hours": 168,
  "actor": { "id": 9, "username": "mod_alice" }
}
```

## Filtering

`GET /api/v1/events?type=post.created&since=2026-05-28T00:00:00Z` returns only matching events newest-first. Pass back the `next_cursor` field to walk history.