Webhooks

OwnerRez has an API, which is available to any user or third party who needs to communicate with our software programmatically.  Learn more how to authenticate with our API or how to build an OAuth based "app" that others can connect to for your brand.

Once you create an app, you'll need to use "webhooks" to receive updates from OwnerRez automatically when certain entities change. 

• What is a webhook?
• Consuming a webhook
• The webhook data format
  • Fields
  • Actions
  • Entity Types
  • Booking Categories
  • Property Categories
• Securing your webhook
• Debugging your webhook
• Keeping track of block/bookings over time
• Important gotchas
• Failure Policy

What is a webhook?

A webhook (also called a web callback or HTTP push API) is a way for an app to provide other applications with real-time information. A webhook delivers data to other applications as it happens, meaning you get data immediately. Unlike typical APIs where you would need to poll for data very frequently in order to get it close to real-time. This makes webhooks much more efficient for both provider and consumer.

Webhooks are sometimes referred to as "Reverse APIs," as they give you what amounts to an API spec, and you must design an API for the webhook to use. The OwnerRez webhook will make an HTTP request to your app (as a POST), and you will then be charged with interpreting it.

Consuming a webhook

The first step in consuming the OwnerRez webhook is to give us the URL where you want requests delivered to. This is done by setting the "URL" field under the Webhooks section of your OAuth app inside the Developer/API settings page in your OwnerRez account.

This means that you also need to set up a URL in your app that’s accessible from the public web so that OwnerRez can reach out, across the internet, and make requests to the URL.

Along with the URL itself, you'll need to also set a User and Password value that we'll use to securely make the request so other anonymous requests don't get through. This will make sure only OwnerRez is able to make requests to your URL and no one else.

Your application should respond to webhooks from OwnerRez with a http code in the 2xx range if there are no problems consuming the webhook.

The webhook data format

Webhooks are sent as POST requests over HTTP with the payload formatted as JSON in the request body.

{
  "id": 12345,
  "user_id": 56789,
  "action": "entity_update",
  "entity_type": "property",
  "entity_id": 12345,
  "category": "descriptions"
}

The payload is made up of 5 fields, though others may be added at a later date. Your code should be designed to ignore fields you have not implemented so that updates to this format do not cause your application to fail.

Fields

Actions

The following actions are supported:

• entity_create
• entity_update
• entity_delete
• application_authorization_revoked
• webhook_test

Entity Types

There are many different entity types that may appear.  Currently, the following entity types are supported:

• api_application
• booking
• guest
• property
• message

Over time, this list will grow as new entity types are supported. Most types (but not all) can be enabled or disabled on your application configuration within OwnerRez.

Booking Categories

To limit how often you need to get updates, we also include a category depending on the type of entity that the webhook is for.  This is so that you know what part of the entity changed, not just that the entity changed overall.  For instance, bookings, as well as financial transactions and other information, can change over time.

Currently, the following categories are supported for booking webhooks:

• agreement
• availability
• canceled
• charge
• dates
• doorcode
• financial
• notes
• payment
• property
• time
• transaction

Property Categories

To limit how often you need to get updates, we also include a category depending on the type of entity that the webhook is for.  This is so that you know what part of the entity changed, not just that the entity changed overall.  For instance, properties are quite large and include listing content (amenities, photos, descriptions) as well as rules and other information.  It's helpful to know that amenities changed but not photos.

Currently, the following categories are supported for property webhooks:

• rates
• surcharges
• taxes
• rules
• availability
• descriptions
• location
• rooms
• photos

What do I do with this data?

The payload described above is intentionally kept small to minimize security vulnerabilities and maximize performance. However, this means that you will need to make additional API calls to load all the details about an event. You should use the entity_type and entity_id to distinguish which API calls are needed.

Securing your webhook

Because our webhooks deliver data to publicly available URLs in your application, there’s the chance that someone else could find that URL and then provide you with false data. To prevent this from happening, you should employ a couple of techniques. First, force TLS connections (https). Second, implement basic authentication and provide a unique username and password to OwnerRez on your OAuth app configuration page.

Debugging your webhook

The simplest way to test your webhook is to use the "Send a Test Webhook" button within OwnerRez. This will send your application a webhook that looks like this:

{
  "id": 12345,
  "user_id": 56789,
  "action": "webhook_test",
  "entity_type": "api_application",
  "entity_id": 12345
}

(The user_id and entity_id values will be your user identifier and the identifier of your OAuth application.)

If there are any problems with authentication, or if your application responds with a non-2xx HTTP code for any reason, the webhook will fail. This will be shown in OwnerRez on the webhooks list. You can find more information about the failure by clicking on the "Data" column.

Webhooks that fail will be retried on an exponentially increasing time scale. This means we'll retry quickly at first, but multiple failures will delay the next retry for longer and longer time periods. A failing webhook will not be retried more than 10 times. After 10 retries, a webhook will be marked Failed permanently.

Keeping track of block/bookings over time

If your application works with a user's bookings, a common scenario is the need to keep track of a list of bookings for the user and know when new bookings come in or certain fields/statuses change on existing bookings. Here's our recommendation on how to do that:

1. Upon initial connection, download a list of current bookings/blocks using the booking list API
2. Listen for entity_insert webhooks to know when bookings/blocks come in
3. Listen for entity_update webhooks to know when a booking is updated or canceled
4. Listen for entity_delete webhooks to know when a booking is deleted

Here are a couple of common statuses that can change over time and how to track them:

Block vs Booking. To know if an item is a booking or a blocked-off time, look at the is_block field. You can also see types of blocks using the type field -- quote holds and linked availability will also show up as blocks. A booking will never change back to a block, but a block could be converted into a booking. In that case you'd get an entity_update webhook.

Cancellation and Deletion. To know if an item has been canceled, look at the status field or check for the existence of the canceled_utc field. You'll get an entity_update webhook when the cancellation status changes. It is possible for a canceled booking to be reactivated, in which case you'd get another entity_update webhook.

Most bookings aren't deletable -- deletion isn't allowed if there's referencing information like credit card transactions or channel/calendar linkages -- but blocks can usually be deleted. If a booking/block is deleted, you'll get an entity_delete webhook. It is not possible for a deleted booking to be un-deleted.

Important gotchas

There are a couple things to keep in mind when creating webhook consumers:

• Webhooks deliver data to your application and will stop paying attention after 10 retries. This means if your application has an error your data may be lost.
• Because we resend requests if your application errors out, it is possible for you to receive duplicate requests. If your application processed the request and still sent an error, there may be duplicate data in your app.
• Webhooks can make a lot of requests. If your app users have a lot of events to tell you about, they may end up DDOSing your app. Make sure your application can handle the expected scale of your webhook.

Failure Policy

Some partner OAuth Apps occasionally respond to OwnerRez data pushes with errors. When this happens at too high a volume, it can cause problems not only for that partner but also for other OwnerRez partners. Integrations of Partner OAuth Apps with high failure rates and significant OwnerRez processing power usage will be automatically disabled by OwnerRez.

When too many failures occur, OwnerRez will auto-disable partner OAuth App integration webhooks, along with the following process.

• Skip all retries for auto-disable apps
• Prevent old retries when and if the webhooks are re-enabled
• Notifying the partner that their webhooks are disabled with the following message, "Webhooks have been paused due to a high incidence of errors from the remote server. Please review the HTTP failures in the webhooks below and correct any issues. Then re-enable webhooks."