# Slim Payloads & Hydration

At Lavanda we publish webhooks when events happen in our system. We deliberately keep
these messages **slim** — a payload tells you *what* happened and gives you the key
identifiers, but it does **not** carry a full copy of the record.

To act on an event you **enrich** it: take the identifiers from the payload and call our
GraphQL API to load exactly the data you need (assuming your API credentials have
permission to do so). This enrichment step is the heart of the pattern — the webhook is
the trigger, GraphQL is the source of truth.

## Why slim payloads?

* **You fetch only what you need.** Rather than parsing a large, fixed payload, you shape
  a GraphQL query to your use case and read back just those fields.
* **The data is always current.** Enriching at the moment you process the event means you
  read the latest state, never a stale snapshot baked into a message queued earlier.
* **The contract stays stable.** Adding fields to a record never changes the shape of the
  webhook, so your endpoint keeps working as our data model evolves.
* **Access is enforced on read.** Enrichment runs against your credentials, so sensitive
  data is never pushed to an endpoint that shouldn't see it.

## Worked example: `v1.booking.created`

When a booking is created we publish a [`v1.booking.created`][booking-created] event. The
payload carries the event metadata plus the identifiers you need to enrich it — the
`booking.id` and the `workspace.id`:

```json
{
  "id": "booking_363c6cdf-7920-4752-9606-9ea48bb538b7",
  "type": "v1.booking.created",
  "booking": {
    "id": "1234567890"
  },
  "workspace": {
    "id": "1234567890"
  }
}
```

That's all the event gives you — no dates, no guest, no unit. To do anything useful you
**enrich** it: take `booking.id` and query the API for the fields you care about. The
query below pulls the check-in / check-out dates and walks the accommodation hierarchy
down through the unit, unit type and building:

```graphql
query Booking($bookingId: ID!) {
  bookings {
    booking(bookingId: $bookingId) {
      checkIn
      checkOut
      accommodations {
        current
        unit {
          id
          code
          unitType {
            id
            code
            building {
              id
              name
            }
          }
        }
      }
      status
    }
  }
}
```

Pass the `booking.id` from the payload as the query variable:

```json
{
  "bookingId": "1234567890"
}
```

The same pattern applies to every event we publish: **receive the event → read the
identifier → enrich via GraphQL.** Browse the full catalogue of event types and their
payloads at [webhooks-docs.lavanda.app][catalogue].

## Next steps

* New to our GraphQL conventions? Start with [API Paradigms](/concepts/api-paradigms/).
* For authenticating your API calls, see [Auth](/concepts/auth/).

[booking-created]: https://webhooks-docs.lavanda.app/#v1.booking.created
[catalogue]: https://webhooks-docs.lavanda.app/