Webhooks: Reservations

Webhook notifications for reservation activity.

Guesty's Open API allows you to send various reservation-related webhook notifications to your application's notification URL(s).

What Notifications Can I Receive?

Reservation notifications are sent by Guesty when there are reservation-related events such as:

  • New reservation/booking request
  • Reservation alteration (status changes, listing change, extend/shorten dates, etc.)

New Reservation / Booking Request Notification

This webhook notification is sent whenever a new reservation or booking request is created or imported from the booking channel within your Guesty account. Learn how to create this webhook here.

Notification Payload

Body ParameterData TypeDescription
reservationobjectThe new reservation object.
eventstringreservation.new

New Reservation / Booking Request Notification Example

{
    "reservation": {
        "__v": 0,
        "lastUpdatedAt": "2017-10-01T16:13:25.711Z",
        "status": "inquiry",
        "checkIn": "2017-10-04T12:00:00.000Z",
        "checkOut": "2017-10-08T07:00:00.000Z",
        "nightsCount": 4,
        "guestsCount": 2,
        "checkInDateLocalized": "2017-10-04",
        "checkOutDateLocalized": "2017-10-08",
        "guestId": "586147bfb2acb2100022cfaf",
        "listingId": "59ac245d27cb310f0017afe3",
        "accountId": "563e0b6a08a2710e00057b82",
        "source": "Manual",
        "isReturningGuest": true,
        "_id": "59d11425af06e3100095e9fe",
        "customFields": [],
        "confirmedPreBookings": [],
        "log": [],
        "pendingTasks": [],
        "review": {
            "shouldReview": true
        },
        "money": {
            "ownerRevenue": 3123.9,
            "commissionIncTax": 347.1,
            "commissionTax": 0,
            "commissionTaxPercentage": 0,
            "commission": 347.1,
            "commissionFormula": "net_income*0.1",
            "netIncome": 3471,
            "netIncomeFormula": "host_payout",
            "isFullyPaid": false,
            "balanceDue": 3471,
            "paymentsDue": 0,
            "totalPaid": 0,
            "totalRefunded": 0,
            "currency": "EUR",
            "fareAccommodation": 3436,
            "fareCleaning": 35,
            "hostPayout": 3471,
            "subTotalPrice": 3471,
            "hostPayoutUsd": 4101.842934040806,
            "autoPaymentsPolicy": [],
            "payments": [],
            "invoiceItems": [
                {
                    "title": "Accommodation fare",
                    "amount": 3436,
                    "currency": "EUR",
                    "isLocked": true,
                    "_id": "59d11425af06e3100095e9ff"
                },
                {
                    "title": "Cleaning fee",
                    "amount": 35,
                    "currency": "EUR",
                    "isLocked": true,
                    "_id": "59d11425af06e3100095ea00"
                }
            ]
        },
        "guest": {
            "airbnb": {
                "id": 1544452897796
            },
            "airbnb2": {
                "index": "index678136",
                "id": 1544452897796
            },
            "policy": {
                "marketing": {
                    "isAccepted": false,
                    "dateOfAcceptance": null
                }
            },
            "verifications": [],
            "emails": [
                "[email protected]"
            ],
            "phones": [],
            "communicationMethods": [
                "email"
            ],
            "_id": "5c0e7b21f9f87e00378892f8",
            "fullName": "Lebron James",
            "firstName": "Lebron",
            "lastName": "James",
            "email": "[email protected]",
            "confirmed": true
        },
        "integration": {
            "_id": "5784a3cc64ce9c0e00ecaf1e",
            "platform": "manual",
            "limitations": {
                "availableStatuses": []
            }
        },
        "createdAt": "2017-10-01T16:13:25.699Z",
        "id": "59d11425af06e3100095e9fe"
    },
    "event": "reservation.new"
}

Reservation Alteration Notifications

This webhook notification is sent whenever a change has been made to a reservation / booking request. Learn how to create this webhook here.

📘

Number of Webhooks

Alterations to reservations may produce two webhooks for the same event. These are different and we recommend that you analyze them to derive effective schema for mapping with your systems.

Notification Payload

Body ParameterData TypeDescription
reservationobjectThe altered reservation object.
reservationBeforeobjectThe original reservation object.
eventstringreservation.updated

Reservation / Booking Request Alteration Notification Example

{
    "reservation": {
        "_id": "59d0ba61b57d3b04004255e2",
        "lastUpdatedAt": "2017-10-01T15:57:25.426Z",
        "daysInAdvance": 29,
        "accountId": "563e0b6a08a2710e00057b82",
        "listingId": "59ac245d27cb310f0017afe3",
        "guestId": "5967610932d1ee1000574c9c",
        "status": "confirmed",
        "confirmationCode": "RU-rAwXPp",
        "checkInDateLocalized": "2017-10-30",
        "checkOutDateLocalized": "2017-10-31",
        "guestsCount": 2,
        "source": "Manual",
        "checkIn": "2017-10-30T13:00:00.000Z",
        "checkOut": "2017-10-31T08:00:00.000Z",
        "nightsCount": 1,
        "confirmedAt": "2017-10-01T09:50:25.372Z",
        "__v": 1,
        "customFields": [],
        "confirmedPreBookings": [],
        "log": [
            {
                "event": "Booking was confirmed successfully",
                "_id": "59d0ba61b57d3b04004255e4",
                "changes": [],
                "at": "2017-10-01T09:50:25.499Z"
            }
        ],
        "pendingTasks": [],
        "review": {
            "shouldReview": true
        },
        "money": {
            "currency": "EUR",
            "hostPayout": 35,
            "guestTotalPrice": 1,
            "alreadyPaid": 0,
            "fareAccommodation": -34,
            "fareCleaning": 35,
            "ownerRevenue": 31.5,
            "commissionIncTax": 3.5,
            "commissionTax": 0,
            "commissionTaxPercentage": 0,
            "commission": 3.5,
            "commissionFormula": "net_income*0.1",
            "netIncome": 35,
            "netIncomeFormula": "host_payout",
            "isFullyPaid": false,
            "balanceDue": 35,
            "paymentsDue": 35,
            "totalPaid": 0,
            "totalRefunded": 0,
            "subTotalPrice": 35,
            "hostPayoutUsd": 1.1817467398561814,
            "autoPaymentsPolicy": [
                {
                    "chargeType": "REST_OF_PAYMENT",
                    "amount": 0,
                    "useGuestCard": true,
                    "_id": "59aebb10edad8d0f00d6954c",
                    "scheduleTo": {
                        "reservationEvent": "CHECK_OUT",
                        "timeRelation": {
                            "relation": "AT",
                            "unit": "HOURS",
                            "amount": 1
                        }
                    }
                }
            ],
            "payments": [
                {
                    "policyItemId": "59aebaf3edad8d0f00d68f55",
                    "shouldBePaidAt": "2017-10-30T13:00:00.000Z",
                    "currency": "EUR",
                    "amount": 10.5,
                    "paymentMethodId": "589894a91d756b9c47ce1e87",
                    "_id": "59d0ba61b57d3b04004255e6",
                    "receiptTargets": [],
                    "attempts": [],
                    "createdAt": "2017-10-01T09:50:25.783Z",
                    "refunds": [],
                    "status": "PENDING"
                },
                {
                    "policyItemId": "59aebb10edad8d0f00d6954c",
                    "shouldBePaidAt": "2017-10-31T08:00:00.000Z",
                    "currency": "EUR",
                    "amount": 24.5,
                    "paymentMethodId": "589894a91d756b9c47ce1e87",
                    "_id": "59d0ba61b57d3b04004255e5",
                    "receiptTargets": [],
                    "attempts": [],
                    "createdAt": "2017-10-01T09:50:25.782Z",
                    "refunds": [],
                    "status": "PENDING"
                }
            ],
            "invoiceItems": [
                {
                    "title": "Cleaning fee",
                    "amount": 35,
                    "currency": "EUR",
                    "isLocked": true,
                    "_id": "59d0ba61b57d3b04004255e3"
                }
            ]
        },
        "integration": {
            "_id": "596b6f5aa6bd32100050be2a",
            "platform": "rentalsUnited",
            "rentalsUnited": {
                "id": 134019397,
                "listingId": 1491473,
                "channelReservationId": null
            },
            "limitations": {
                "availableStatuses": []
            }
        },
        "createdAt": "2017-10-01T09:50:25.380Z",
        "id": "59d0ba61b57d3b04004255e2"
    },
    "reservationBefore": {
        "_id": "59d0ba61b57d3b04004255e2",
        "lastUpdatedAt": "2017-10-01T14:50:28.254Z",
        "daysInAdvance": 29,
        "accountId": "563e0b6a08a2710e00057b82",
        "listingId": "59ac245d27cb310f0017afe3",
        "guestId": "5967610932d1ee1000574c9c",
        "status": "confirmed",
        "confirmationCode": "RU-rAwXPp",
        "checkInDateLocalized": "2017-10-30",
        "checkOutDateLocalized": "2017-10-31",
        "guestsCount": 2,
        "source": "Manual",
        "checkIn": "2017-10-30T13:00:00.000Z",
        "checkOut": "2017-10-31T08:00:00.000Z",
        "nightsCount": 1,
        "confirmedAt": "2017-10-01T09:50:25.372Z",
        "customFields": [],
        "confirmedPreBookings": [],
        "log": [
            {
                "event": "Booking was confirmed successfully",
                "_id": "59d0ba61b57d3b04004255e4",
                "changes": [],
                "at": "2017-10-01T09:50:25.499Z"
            }
        ],
        "pendingTasks": [],
        "review": {
            "shouldReview": true
        },
        "money": {
            "currency": "EUR",
            "hostPayout": 35,
            "guestTotalPrice": 1,
            "alreadyPaid": 0,
            "fareAccommodation": -34,
            "fareCleaning": 35,
            "ownerRevenue": 31.5,
            "commissionIncTax": 3.5,
            "commissionTax": 0,
            "commissionTaxPercentage": 0,
            "commission": 3.5,
            "commissionFormula": "net_income*0.1",
            "netIncome": 35,
            "netIncomeFormula": "host_payout",
            "isFullyPaid": false,
            "balanceDue": 35,
            "paymentsDue": 35,
            "totalPaid": 0,
            "totalRefunded": 0,
            "subTotalPrice": 35,
            "hostPayoutUsd": 1.1817467398561814,
            "autoPaymentsPolicy": [
                {
                    "chargeType": "REST_OF_PAYMENT",
                    "amount": 0,
                    "useGuestCard": true,
                    "_id": "59aebb10edad8d0f00d6954c",
                    "scheduleTo": {
                        "reservationEvent": "CHECK_OUT",
                        "timeRelation": {
                            "relation": "AT",
                            "unit": "HOURS",
                            "amount": 1
                        }
                    }
                }
            ],
            "payments": [
                {
                    "policyItemId": "59aebaf3edad8d0f00d68f55",
                    "shouldBePaidAt": "2017-10-30T13:00:00.000Z",
                    "currency": "EUR",
                    "amount": 10.5,
                    "paymentMethodId": "589894a91d756b9c47ce1e87",
                    "_id": "59d0ba61b57d3b04004255e6",
                    "receiptTargets": [],
                    "attempts": [],
                    "createdAt": "2017-10-01T09:50:25.783Z",
                    "refunds": [],
                    "status": "PENDING"
                },
                {
                    "policyItemId": "59aebb10edad8d0f00d6954c",
                    "shouldBePaidAt": "2017-10-31T08:00:00.000Z",
                    "currency": "EUR",
                    "amount": 24.5,
                    "paymentMethodId": "589894a91d756b9c47ce1e87",
                    "_id": "59d0ba61b57d3b04004255e5",
                    "receiptTargets": [],
                    "attempts": [],
                    "createdAt": "2017-10-01T09:50:25.782Z",
                    "refunds": [],
                    "status": "PENDING"
                }
            ],
            "invoiceItems": [
                {
                    "title": "Cleaning fee",
                    "amount": 35,
                    "currency": "EUR",
                    "isLocked": true,
                    "_id": "59d0ba61b57d3b04004255e3"
                }
            ]
        },
        "integration": {
            "_id": "596b6f5aa6bd32100050be2a",
            "platform": "rentalsUnited",
            "rentalsUnited": {
                "id": 134019397,
                "listingId": 1491473,
                "channelReservationId": null
            },
            "limitations": {
                "availableStatuses": []
            }
        },
        "createdAt": "2017-10-01T09:50:25.380Z",
        "id": "59d0ba61b57d3b04004255e2"
    },
    "event": "reservation.updated"
}
{
    "reservationId": "59d0ba61b57d3b04004255e2",
    "conversation": {
        "_id": "59d0ba63b57d3b04004255fe",
        "accountId": "563e0b6a08a2710e00057b82",
        "guestId": "5967610932d1ee1000574c9c",
        "conversationWith": "Guest",
        "lastUpdatedAt": "2017-10-01T15:48:22.035Z",
        "subject": "Message about your reservation",
        "lastSyncedAt": "2017-10-01T14:28:06.834Z",
        "readLog": [
            {
                "by": "59d0c0dc101978100075bbd4",
                "_id": "59d0c13ecee2571000637413",
                "at": "2017-10-01T10:19:42.627Z"
            }
        ],
        "isRead": true,
        "language": "en",
        "thread": [
            {
                "module": "sms",
                "type": "fromGuest",
                "body": "I know",
                "from": "972504042351",
                "to": "447520619995",
                "_id": "59d10e46af06e3100095e261",
                "createdAt": "2017-10-01T15:48:22.035Z",
                "id": "59d10e46af06e3100095e261"
            },
            {
                "body": "Love you for booking with us!",
                "status": "completed",
                "reservationId": "59d0ba61b57d3b04004255e2",
                "module": "sms",
                "to": "972504042351",
                "from": "447520619995",
                "type": "fromHost",
                "_id": "59d0c8e186f2fd04003805d8",
                "sentAt": "2017-10-01T10:54:18.803Z",
                "createdAt": "2017-10-01T10:52:17.630Z",
                "id": "59d0c8e186f2fd04003805d8"
            },
            {
                "body": "you're the man!",
                "status": "completed",
                "reservationId": "59d0ba61b57d3b04004255e2",
                "module": "sms",
                "to": "972504042351",
                "from": "447520619995",
                "type": "fromHost",
                "_id": "59d0c8e086f2fd04003805d6",
                "sentAt": "2017-10-01T10:52:35.470Z",
                "createdAt": "2017-10-01T10:52:16.954Z",
                "id": "59d0c8e086f2fd04003805d6"
            }
        ],
        "createdAt": "2017-10-01T09:50:27.082Z",
        "pendingTasks": [],
        "integration": {
            "platform": "rentalsUnited",
            "_id": "596b6f5aa6bd32100050be2a"
        },
        "id": "59d0ba63b57d3b04004255fe"
    },
    "message": {
        "module": "sms",
        "type": "fromGuest",
        "body": "I know",
        "createdAt": "2017-10-01T15:48:22.035Z",
        "from": "972504042351",
        "to": "447520619995"
    },
    "event": "reservation.messageReceived"
}

FAQs

Why am I receiving two webhooks for the same reservation update?

To ensure all reservation changes are captured after the event, two webhooks are generated. They differ in content, and we recommend you analyze their schema and content to map with your systems.