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 event. The payload carries the event metadata plus the identifiers you need to enrich it — the booking.id and the workspace.id:

{
  "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:

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:

{
  "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.

Next steps

• New to our GraphQL conventions? Start with API Paradigms.
• For authenticating your API calls, see Auth.