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.
Webhooks are only available for OAuth-authenticated apps.
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
- Securing your webhook
- Debugging your webhook
- Keeping track of block/bookings over time
- Important gotchas
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.
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 OwnerRz 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.
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.
|user_id||Integer||The unique identifier of the user on which the event or action occurred.|
|action||String||The event or action that occurred, limited to the list below.|
|entity_type||String||The type of record that was modified, limited to the list below. For "entity_..." actions only.|
|entity_id||Integer||The unique identifier of the record that was modified. For "entity_..." actions only.|
|category||String||The part of the record that was changed. Only included if entity_type is property.|
The following actions are supported:
There are many different entity types that may appear. Currently, the following entity types are supported:
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.
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:
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.
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.
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.
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:
- Upon initial connection, download a list of current bookings/blocks using the booking list API
- Listen for
entity_insertwebhooks to know when bookings/blocks come in
- Listen for
entity_updatewebhooks to know when a booking is updated or canceled
- Listen for
entity_deletewebhooks 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
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
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.
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.