> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omneo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Event Contexts

> Understanding the richer Event Context payloads returned in webhooks and reactions.

An Event Context is the payload Omneo provides when an event fires, via a webhook or a reaction. It differs from a standard API response in that it includes enriched, related data alongside the triggering object to minimise the need for additional API calls.

## Why contexts are different from API responses

A standard `GET /api/v3/profiles/{id}` response returns the profile object. The profile event context returned by a `profile.updated` webhook also includes:

* Aggregations (`spend_12m`, `shop_count`, etc.)
* `flattened_tags` (tags as a flat array for easier JSON Logic evaluation)
* `flattened_statuses`
* Current tier and tier definition
* Profile attribute objects (comms, appearance)

This means your webhook handler can act on the event without making additional API calls back to Omneo.

## Profile event context

Fields available at root level (accessed directly as `first_name`, not `profile.first_name`):

```json theme={null}
{
  "id": "8fc344db-713e-4590-ab26-e82d77ba3313",
  "first_name": "Jane",
  "last_name": "Smith",
  "email": "jane@example.com",
  "gender": "female",
  "tier_handle": "gold",
  "joined_at": "2023-01-15 00:00:00",
  "birth_year": 1985,
  "birth_month": 9,
  "birth_day": 15,
  "flattened_tags": ["vip", "stylist-client"],
  "flattened_statuses": ["active"],
  "reward_balance": 25.00,
  "point_balance": 1500,
  "combined_balance_dollars": 40.00,
  "aggregations": {
    "spend_12m": 2450.00,
    "spend_all": 12800.00,
    "spend_atv_12m": 175.00,
    "shop_count": 14,
    "shop_days": 12
  },
  "tier": {
    "handle": "gold",
    "name": "Gold"
  },
  "attributes": {
    "comms": {
      "email_promo": true,
      "email_optout": false,
      "sms_promo": false
    },
    "appearance": {
      "size_top": "12",
      "size_shoe": "8"
    }
  }
}
```

## Transaction event context

For `transaction.created` and `transaction.updated` events, the context includes the transaction and the linked profile:

```json theme={null}
{
  "id": "txn-uuid",
  "profile_id": "profile-uuid",
  "total": 149.95,
  "total_original": 199.95,
  "transacted_at": "2025-06-15 14:32:00",
  "external_id": "ORDER-10334",
  "receipt_ref": "659",
  "location_id": 2,
  "items": [...],
  "profile": {
    "id": "profile-uuid",
    "first_name": "Jane",
    "tier_handle": "gold",
    "aggregations": { ... }
  }
}
```

## Tier achieved context

For `tier.achieved` events, the context includes the profile and the tier definition that was achieved:

```json theme={null}
{
  "profile_id": "profile-uuid",
  "definition": {
    "handle": "gold",
    "name": "Gold"
  },
  "profile": { ... }
}
```

## Rating event context

For `rating.created` and `rating.updated` events, the context includes the rating and, when a `transaction_id` is present, the linked transaction:

```json theme={null}
{
  "id": "rating-uuid",
  "profile_id": "profile-uuid",
  "source": "pos",
  "product_id": "product-uuid",
  "product_variant_id": "variant-uuid",
  "transaction_id": "txn-uuid",
  "transaction": {
    "id": "txn-uuid",
    "profile_id": "profile-uuid",
    "total": 149.95,
    "transacted_at": "2025-06-15 14:32:00",
    "external_id": "ORDER-10334"
  },
  "interaction_id": "interaction-uuid",
  "staff_id": "staff-uuid",
  "external_id": "ext-rating-123",
  "profile": {
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@example.com",
    "identities": [...]
  }
}
```

The `transaction` field is `null` when the rating has no associated transaction.

## Using contexts in reactions

All fields in an event context are available as variables in reaction filters and target templates. See [JSON Conditions](/dev-guides/reactions/json-conditions) for how to reference them.

## Context vs API response

If you need data not included in the context (e.g., full address list, complete transaction history), make a follow-up API call using the `profile_id` from the context.