Subscribe to webhooks

What is a webhook?

A webhook lets your app receive real-time updates from other systems, so you get important information as soon as it happens. In many cases, this is more efficient than polling an API for changes.

---
config:
  layout: elk
  theme: redux-color
  look: neo
  fontFamily: '''Jetbrains Mono Variable'', monospace'
---
sequenceDiagram
    participant Client
    participant Server
    Client->>Server: Subscribe to webhook events
    Server-->>Client: Subscription confirmed
    Note over Server: Event occurs on platform
    Server->>Client: Send webhook notification
    Client-->>Server: 200 OK
    Note over Client: Validate signature
    Client->>Server: Commence data retrieval
    Note over Client,Server: Cycle complete

With Guesty's Open API, you can set up webhook subscriptions to keep your application updated as soon as something changes. Using webhooks helps you get the most value from the API.

Why subscribe to webhooks?

After you finish your initial Guesty Open API integration and data sync, subscribe to the webhook events that matter to your business. Webhooks help you stay current with account activity, save time, and sync only the data that has changed since your last update. For example, you can subscribe to a webhook for new reservations and be notified whenever a booking is created.

Table of Supported Webhooks

The following table summarizes the Webhooks Guesty offers, with links to more detailed guides for each type.

Subscribe to events

To subscribe to webhook events, follow the steps in the reference documentation. Each webhook subscription includes:

1. URL: Must be HTTPS on port 443 with a publicly resolvable hostname. For example, https://www.hookurl.com. Keep URLs per subscription unique to avoid delivery issues.
2. Events: A list of events the URL is subscribed to.

Example

{
  "url": "https://www.hookurl.com",
  "events": [
    "reservation.created.v2",
    "reservation.updated.v2",
    "calendar.updated.v2"
  ]
}

Keep your subscriptions up to date by editing them or replacing them (delete then create) as needed. Avoid creating duplicate subscriptions with the same URL, since this can lead to missed notifications.

Validate webhooks

Each subscribed endpoint receives its own unique signing key that you can use to validate the events you receive from Guesty. To validate:

1. Retrieve your unique webhook secret with GET /webhooks-v2/secret or from your webhooks developer dashboard in your Guesty account
2. Follow Svix’s instructions on how to use your secret to validate your webhook payloads

Delivery behavior

Retries and auto-disable

Guesty attempts to deliver each webhook message using a retry schedule with exponential backoff. Each message is retried according to the following schedule, with each period starting after the failure of the preceding attempt:

• Immediately
• 5 seconds
• 5 minutes
• 30 minutes
• 2 hours
• 5 hours
• 10 hours
• 10 hours (in addition to the previous)

If an endpoint is removed or disabled, delivery attempts to that endpoint will also be disabled. For example, an attempt that fails three times before eventually succeeding will be delivered roughly 35 minutes and 5 seconds after the first attempt. After all the attempts are concluded, the message will be marked as Failed for this endpoint.

If all attempts to the specified endpoint fail for 5 days, the endpoint will be automatically disabled. The clock starts only after multiple deliveries fail within a 24-hour span, with at least a 12-hour gap between the first and last failures.

Contact Guesty API Support to request reactivation of your disabled webhook subscription.

Handle an event

• Acknowledge: To indicate that a webhook has been processed, return a 2xx status code (200-299) within a reasonable time frame (15s). Any other status code, including 3xx redirects, is treated as a failure.
• Parse: Analyze the data to identify the event type, the updated object, and the update type.
• Validate (optional): Use your secret to validate the webhook if required.
• Fetch: Invoke Guesty’s Open API to retrieve the complete details.
• Compare: Evaluate the fresh data against your cached version to identify the exact change(s).

Ordering and duplicates

Guesty processes events asynchronously, so you may receive events out of order on occasion. Recovery processes may also emit historical events you’ve already received. To ensure you process events in the correct order and ignore duplicates, monitor and process according to the following:

• Deduplicate on the svix-id and the Guesty meta.eventId (reservation v2 events contain dedup logic, so you should only receive unique payloads from them)
• Order according to the __v or lastUpdatedAt dates contained in the data. Rely on the fresh data you ingest to drive your state, not the order of events.

Newer events like the reservation v2 ones deduplicate by design and provide a publishedAt date and a subEvent value to make this even easier.

FAQs