Reservation webhooks migration

What has changed?

Guesty has introduced two new reservation webhook events to replace our legacy ones:

• reservation.created.v2 replaces reservation.new
• reservation.updated.v2 replaces reservation.updated and reservation_update_shortlist

The new webhook events separate financial and payment information from stay details, making it easier to track changes and manage reservations efficiently. Here’s what’s improved:

• Lean payloads: With less data sent in each webhook, your system processes updates faster. You’ll see only the key stay details and the change sub-types. To access full financial, listing, or guest information, simply use the relevant API endpoint.
• Clearer change tracking: The updated event shows which fields or reservation section changed, so you know exactly what triggered the webhook and can respond quickly.
• Improved sequencing: Each event includes a timestamp (publishedAt) and subtype, helping you keep updates in order and avoid processing errors.

We recommend switching to the v2 events, as the legacy webhooks will be phased out by the end of 2026. If you run into any issues during migration, reach out to us, and we’ll help you resolve them.

How to migrate

1. Subscribe: Add the v2 events to your existing webhook subscription (PUT/webhooks/{id})
2. Observe: Your endpoint will begin receiving both legacy and v2 events. Validate that the v2 delivery is consistent in your test environment.
3. Switch logic: Update your system to use the v2 payload first. If you need more details, use the reservationId to pull extra information from the Open API.
   1. GET /reservations-v3
   2. GET /guest-folio/overview
   3. GET /guest-folio/invoice-items
   4. GET /listings/{id}
4. Confirm migration: When you’ve tested and are confident in the new setup, move your production accounts to v2.

Handling events

Refer to Guesty’s main webhooks article on how to process webhooks here (Webhook Subscriptions)

Data structure

Legacy data structure

The legacy events emitted the full reservation object and event label, with updates adding a reservationBefore object. Due to the size of the payloads, only the top-level parameters are shown. Perform your own tests to map event shapes.

{
  // The event value will be either `reservation.new`, `reservation.updated`, or `reservation_update_shortlist`
  "event: "reservation.event", 
  "meta": {},
  "reservation": {},
  // The following appears on `reservation.updated` events only
  "reservationBefore": {}
}

Legacy payloads included all settings, pricing, and payment information, which made them difficult to manage. To simplify your workflow and follow webhook best practices, we’ve introduced the new v2 structure, explained below.

V2 Shared data structure (data)

Both events share a common data interface representing the core state of the reservation. These include the following:

V2 metadata (meta)

The meta object contains context about the event itself.

meta.subType reference

Only present on reservation.updated.v2.

meta.changedFields — All possible values

Only present on reservation.updated.v2.

Identifying owner reservations

Currently, there’s no reliable way to identify owner reservations directly from the webhook payload. While data.source may show owner or 'owner-guest, it’s not always enough. To confirm, use the API to retrieve the reservation and check the creationInfo value.

Ordering and idempotency

Guesty processes events asynchronously, so webhooks may sometimes arrive out of order. The v2 events help you keep updates in the right sequence and avoid duplicates. Here’s how:

• Use publishedAt to determine the chronological order of webhooks that may arrive out of order
• To optimize your processing, Guesty performs deduplication for v2 webhooks. If an update occurs but none of the tracked changedFields (e.g., status, check-in, guests) actually change, a webhook will not be emitted.

Known issues

We’re working on new webhooks and endpoints for reservation financial and payment changes. Until these are ready, you can continue using the legacy resources. If you need help accessing information, contact our support team, and we’ll assist you.