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.

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 job updates:

• job.scheduled
• job.in_progress
• job.completed
• job.cancelled
• job.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.

module Api
  module V1
    class WebhooksController < ActionController::API
      # POST /api/v1/webhook
      def webhook
        event_params = params
        event = ::OpenStruct.new(event_params)

        begin
          # Handle the event
          case event.name
          when 'job.scheduled'
            data = event.data
            # Contains the Job attributes from :object key
            # and previous Job attributes from :object_previous_attributes key
            current_job_attributes = data[:object]
            previous_job_attributes = data[:object_previous_attributes]
            # Then define and call a method to handle the event
          when 'job.in_progress'
            # Handle job in progress
          when 'job.completed'
            # Handle job completed
          when 'job.cancelled'
            # Handle job cancelled
          when 'job.failed'
            # Handle job failed
          end

          body_response = { uuid: event.uuid, name: event.name }
          render json: body_response, status: 200
        rescue => e
          # Handle exceptions in your 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 asynchronously in your application.

5. View Events Sent To Your Webhook

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