Experience the difference of "Elite".

Getting Started

Core Concepts

Overview

Bookings

Bookings & Quotes

Damage Protection

Data Management

Email Template Library

Guests

Hosted Websites

Integrations

Listing Site Integration

Messaging

My Account

Payment Processing

Privacy & Security

Properties

Property Management

Property Sharing

Quotes

Rates

Renter Agreements

Reporting

Reviews

Rules

Security Deposits

Suppressed Email Addresses

Taxes

Technical Stuff

Travel Insurance

Verified Email Domains

Widgets

WordPress Plugin

Channel Management

Integrations

OwnerRez API

Payment Processing

Testing

Change Log

2022

2021

2020

2019

OwnerRez API - 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.

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?

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 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.

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": "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.

Fields

Name Value Type Description
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.

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:

  • guest
  • booking
  • api_application

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.

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.

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.