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 create a webhook endpoint in your application add your webhook endpoint to tidy test your webhook endpoint handle events from tidy in your application 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 \# 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