website logo
⌘K
Getting Started
Getting Started: Rental Properties
Getting Started: Employer Benefits
Getting Started: Residential Homes
Getting Started: Offices
Dashboard
Teams & Users
Users
Teams
Properties/Addresses
Access Instructions
Jobs
Add or Request a Job
View, Edit, or Cancel Jobs
Setting Backup Times
Job Links
Job Reviews or Feedback
Resolving Pro Cancellations
Account Settings
Messages
Notifications
Plans
Access Control / Smartlocks
My Pros
Booking Different Type Of Services With Your Pros
Private Cleaning Payment
Defining your Job Request Strategy
To-Do Lists
To-Do List Links
To-Dos
Do-Nots
Remote Inspections
Custom Fields
Laundry or Linens
Supply Preferences
Integrations
Beds24
Guesty
Hospitable
Hostaway
Hostify
Host Tools
Lodgify
OwnerRez
RemoteLock
Slack
Smoobu
Uplisting
Zapier
Automatic Booking
Billing & Pricing
Billing History
Sending Payments
Bills & Payment Methods
Team Billing
View & Edit Prices
Viewing Billing History
Tips
Refunds
Compliance, Ratings, Safety, Insurance, & Protection
Certifications & Ratings
Satisfaction Guarantee, Disputes, & Protection
Damage Claims
Best Practices
Property Maps
Maintenance Tracking
Inventory Tracking
Inspections
Issue Tracking
Automatic Translation
Other Questions
Developer Overview
API Reference
Webhooks
TIDY Concierge
Reports
Accounting
Docs powered by archbee 
11min

Webhooks

How TIDY Sends Event Notifications to Webhooks

TIDY uses webhooks to send events to your application.

A webhook is an endpoint on your server that receives requests from TIDY, notifying you about events such as completing a cleaning. Add a new endpoint to your server and make sure it's publicly accessible so we can send unauthenticated POST requests.

We send events immediately to your webhook when a user makes an update in the system.

If a webhook attempt fails, then we will attempt to resend the event 10 times total. We gradually increase the length of time between each attempt, in order to give you time to resolve any issues. The first re-attempt will be after a few seconds, the last attempt about a week after the first failure. After 10 failures, you will need to manually update any status via the TIDY website or the API.

Events May Not Be Realtime If Pro is Offline

Some events can occur while a pro is offline, so these events won't be sent until TIDY receives the update. For example: If a pro completes a job at an offline location, their update will be synced when they reconnect to the internet and sync their data. Then, the event will be sent to your webhook.

Types of Events That TIDY Sends to Webhooks

While we may add more event types over time, the current events we send are one of the following booking updates:

  • booking.scheduled
  • booking.in_progress
  • booking.completed
  • booking.cancelled
  • booking.failed

Start Using Webhooks

To start using webhooks, a user typically follows these steps:

  1. Create a webhook endpoint in your application.
  2. Add your webhook endpoint to TIDY.
  3. Test your webhook endpoint.
  4. Handle Events from TIDY in your application.
  5. View TIDY logs to ensure events are handled correctly.

1. Creating a Webhook Endpoint on Your Server

First build a custom endpoint in your application. For each event occurrence, TIDY POSTs the webhook data to your endpoint in JSON format. The full event details are included and can be used directly after parsing the JSON into an Event object. Thus, at minimum, the webhook endpoint needs to expect data through a POST request and confirm successful receipt of that data.

Here is some example code for Ruby, but you can handle webhooks in any language.

Ruby
|
module Api
  module V1
    class WebhooksController < ActionController::API
      # Using Rails API
      # POST /api/v1/webhook
      def webhook
        event_params = params
        event        = ::OpenStruct.new(event_params)
        begin
          # Handle the event
          case event.name
          when 'booking.scheduled'
            data = event.data # contains the Booking attributes from :object key
                              # and previous Booking attributes from :object_previous_attributes key
            current_booking_attibutes   = data[:object]
            previous_booking_attributes = data[:object_previous_attributes]
            # Then define and call a method to handle the successful booking event
          when 'booking.in_progress'
          when 'booking.completed'
          when 'booking.cancelled'
          when 'booking.failed'
          end
          body_response = {
            uuid: event.uuid,
            name: event.name
          }
          render json: body_response, status: 200
        rescue => e
          # Some exception on your code implementation
          body_response = {
            error_message: e.message
          }
          render json: body_response, status: 400
        end
      end
    end
  end
end


2. Add Your Webhook Endpoint to TIDY

Inside the "Developers" section, go to the "Webhooks" section and you should see the option to add a webhook.



3. Test Your Webhook Endpoint

Test your webhook to make sure it receives events correctly by opening the webhook, then tapping "Test". This will send a sample request to the Webhook, which you can use to see the format of the data and handle appropriately.



4. Handle Events from TIDY

Follow these steps to handle events sent via TIDY.

a. Read the event data

TIDY sends the event data in the request body. Each event is structured as an Event object with a type, id, and related TIDY resource nested under data.

b. Handle the event​​

As soon as you have the event object, check the type to know what kind of event happened. You can use one webhook to handle several different event types at once, or set up individual endpoints for specific events.

c. Quickly return a 2xx response

To acknowledge receipt of an event, your endpoint must return a 2xx HTTP status code to TIDY. All response codes outside this range, including 3xx codes, indicate to TIDY that you did not receive the event.

Send a 2xx response to TIDY as quickly as possible because TIDY will retry sending if we do not receive a response.

Because properly acknowledging receipt of the webhook notification is so important, your endpoint should return a 2xx HTTP status code prior to any complex logic that could cause a timeout, then run any long-running processes asyncronously in your application.

5. View Events Sent To Your Webhook

Inside the webhooks section, tap the on the webhook. Then tap "Logs" to view the events sent to that Webhook.

Updated 29 Mar 2023
Did this page help you?
Yes
No
UP NEXT
TIDY Concierge
Docs powered by archbee 
TABLE OF CONTENTS
How TIDY Sends Event Notifications to Webhooks
Events May Not Be Realtime If Pro is Offline
1. Creating a Webhook Endpoint on Your Server
2. Add Your Webhook Endpoint to TIDY
3. Test Your Webhook Endpoint
4. Handle Events from TIDY
5. View Events Sent To Your Webhook