Built by owners, for owners.

Getting Started

Core Concepts

Overview

Bookings & Quotes

Properties

Bookings

Quotes

Guests

Rates

Rules

Reviews

My Account

Messaging

Security Deposits

Insurance and Damage Protection

Taxes

Renter Agreements

Payment Processing

Dynamic Pricing Integrations

Widgets

Listing Site Integration

Property Management

Technical Stuff

Hosted Websites

WordPress Plugin

Door Locks

OwnerRez API

Other Integrations

Reporting

Email Template Library

Data Management

QuickBooks Integration

Privacy & Security

Suppressed Email Addresses

Property Sharing

Channel Management

Page-Specific Help

Payment Processing

Testing

Change Log

2021

2020

2019

OwnerRez API - Webhooks

This support article is under construction 👷

Please pardon the incompleteness while we work on this. We have made the article visible in the meantime because the content may be useful.

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?

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 real-time. This makes webhooks much more efficient for both provider and consumer. The only drawback to webhooks is the difficulty of initially setting them up.

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.

Data format

The majority of webhooks will POST data to you in one of two ways: as JSON (typically) or XML (blech) to be interpreted, or as a form data (application/x-www-form-urlencoded or multipart/form-data). Your provider will tell you how they deliver it (or even give you a choice in the matter). Both of these are fairly easy to interpret, and most web frameworks will do the work for you. If they don’t, you may need to call on a function or two.

...

{
  "user_id": 347311478,
  "action": "entity_update",
  "entity_type": "booking",
  "entity_id": 273411
}

...

Debugging your webhook

Debugging a webhook can be complex at times, as webhooks are principally asynchronous. Thus, you must trigger them and wait, then check the response. This can be tiresome and is fairly inefficient. Luckily there are better ways! We go through many of them in our documentation page on Debugging Webhooks, however, it amounts to the following:

  1. Understand what the webhook provides, by using a tool like RequestBin to collect the webhook’s requests.
  2. Mock the requests using a tool like cURL or Postman.
  3. Test the code on your machine by using a tool like ngrok.
  4. Watch the whole flow using a tool like Runscope.

Securing your webhook

As webhooks deliver data to publicly available URLs in your app, there’s the chance that someone else could find that URL and then provide you with false data. To prevent this from happening, you can employ a number of techniques. The easiest thing to do (and what you should implement before going any further) is to force TLS connections (https). Once you’ve implemented that, you may go forward and further secure your connection:

  1. The first, and most supported, way to secure a webhook is to add tokens to the URL that act as unique identification e.g. ?auth=TK
  2. The next option is to implement Basic Auth, this is also widely supported, and very easy to do.
  3. The first two solutions work great to prevent most attacks, however they have the disadvantage of sending the auth token with the request. The third option is to have the provider sign each request it makes to you and then verifying the signature. This has the disadvantage of requiring the provider to have implemented request signing—meaning if they don’t already, you’re probably out of luck.

Important gotchas

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

  • Webhooks deliver data to your application and may stop paying attention after making a request. This means if your application has an error your data may be lost.
  • Many webhooks will pay attention to responses and re-send requests if your application errors out. If your application processed the request and still sent an error, there may be duplicate data in your app.
  • Understand how your webhook provider deals with responses so you can prepare for the possibility of application errors. Additionally, you may want to check out our tools for help dealing with webhook errors and queuing.
  • Webhooks can make a lot of requests. If your provider has 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.