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
- 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": "booking", "entity_id": 12345 }
The payload is made up of 4 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.|
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.
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.
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.