Is there any documentation available about the data that is passed for the webhooks fired for specific events? Thanks!
Hmm I’m not exactly sure. Have you tried looking at http://rachio.readme.io yet? That might be the information you are looking for.
Thanks for the reply.
I looked there, and I found how to get a list of the events that can be subscribed, and the API call to add a subscription, but nothing that explains what data will be passed into the service endpoint.
Any other suggestions’?
Again, thanks for replying.
Andy
when you call GET /public/notification/webhook_event_type you’ll receive an array of possible webhook subscriptions like this one :
{
"id": "5",
"name": "ZONE_ACTION",
"description": "Event description",
"type": "WEBHOOK"
}
Select an event(s) that you want to subscribe to
Then run POST /public/notification/webhook with the following request body
{
"device": {
"id": "your_device_id"
},
"externalId": "any_string_you_want",
"url": "https://www.yourwebhookurl.com",
"eventTypes": [
{
"id": "1" //get the ID from the GET call you made
},
{
"id": "2"
}
]
}
Hope that helps
Thanks!
I had read the API docs about how to enumerate webhooks, and how to discover what webhooks have been created. What I’m not finding is docs describing the structure of the json data that rachio will pass to those webhooks when called.
For example, let’s say I send a GET to /notification/webhook_event_type and discover the available webhhoks, for example:
{
“createDate”: 1417885403299,
“lastUpdateDate”: 1417885403299,
“id”: 6,
“name”: “RAIN_DELAY”,
“description”: “A rain delay event has occurred”,
“type”: “WEBHOOK”
}
Then i do a POST to subscribe to that event:
{
“device”: {
“id”: “my_device_id”
},
“externalId”: “id_used_by_my_application”,
“url”: “https://www.mywebhookurl.com/events/6”,
“eventTypes”: [
{
“id”: “6”
}
]
}
So now whenever there’s a raind delay, I’ll get notified at https://www.mywebhookurl.com/events/6.
What I’m trying to understand now is, what data will Rachio send me on that request. I’m assuming (perhaps incorrectly) that it’ll be a POST, and there’ll be some JSON data in the post body.
I’m sure I’m just being dense or missing something.
Thanks,
Andy
1 Like
You should recieve a json response in your server. If you’re needing to see what the data is before building, I would check out requestb.in to see the body of incoming requests or use the application debugger to see exactly what you are getting. I went and set up a few webhooks to this bin, you should see events within a day or two
@lucasc I would edit to include “?inspect”, like this (link) otherwise it will fill up by everyone wanting to check out the data.
Clarification: make sure to edit it only in the community post, the webhook should still point to the raw url
(without ?inspect)
This is way over my head. What in the world is a webhook?
1 Like
Imagine you could ask Rachio to call you when ever it started to water your garden and tell you over the phone what made it call you (so you would get a call and hear “Hi Robert, it’s your Rachio controller. I’ve started watering your garden”). Webhook is a way to specify your contact information (a web URL in this case) which Rachio will attempt to access when ever the event you desire has taken place.
For it to be useful, a server which services the URL that was specified, has to understand / make use of the data provided. Some information may come from URL itself (such as “http://yoursite.com/hookanalyzer?info=here”), some may come as part of the request, but in any case the point is to do something when you hear the Rachio “calling”.
Hope that was at all helpful,
Gene
1 Like
@robertokc If you were wondering why Lucas is responding and I’m not… I had to call backup on this one 
Thanks.
Gene explained it well. Webhooks are a service’s way of proactively sending information, but instead of sending it to a person (like via a phone call), it is sending it to another computer. That other computer needs to have an “endpoint” (“phone number”) to receive the “call”, and needs to know what to do with it.
Interesting that Gene used the analogy of a phone call … that’s pretty close to what I’m actually doing. I’ve developed a “hobby” Azure Web App that’s my personal webhook handler. It receives webhooks for everything from my network monitor, to my Visual Studio build server, to my IP phone. I’ve built integrations with Twilio, so a common use case is to send me a text or call me when some event happens, like calling me when there’s a “network down” event or sending me a text whenever a code build finishes.
My plan here is to build webhooks for Rachio to call so I can do logging or get calls/texts whenever events happen like a rain delay or when a rain sensor is triggered, etc.
To Gene’s point, In order for my app to “do something”, it has to be be programmed to understand the data that Rachio is sending. That’s what motivated my question … I know which events Rachio can “call me” about, but not what it will tell me when it calls. Without knowing that, I can’t program my “receiver” to act on it.
I think it’s awesome that Rachio is empowering integrations by providing webhooks. It’s a very powerful tool to drive adoption, because it will be able to participate with a variety of other products and services, and will be a player in the growing “Internet of Things” ecosystem.
I’d humbly suggest, however, that you document the structure of the data being passed. It’s not really practical to have me just start capturing and logging the data for a while, hoping that all the events i’m interested in will fire, and them comb the logged data to figure out the data. It’s unpredictalbe when all the events would actually fire; it’s a tedious and error-prone process; and there will surely be developers building integrations (say to home automation systems) that (sadly) don’t actually have a Rachio controller. Just a set of sample data would be a big help.
Please don’t take that suggestion as criticism. I’m thrilled that you’re providing the integrations. Keep up the good work!
Best,
Andy
.
2 Likes
Andy:
Were you ever able to get your webhooks to work correctly? I have a server running that has subscribed to webhooks but I never get any data from the webhook when my server is called. I know the webhooks are triggering but no data.
You had asked about the data passed in the packet in an earlier request. I assume that the data the is sent when the webhook fires is called out in this JSON documented on the Rachio API page.
{
“id”: “8c3f5e90-fb30-3425-a95d-11fa31244f66”, // ID of the webhook
“summary”: “Scheduled waterings will now run on controller Rachio-E1323B.”, //Summary of the event
“hidden”: false, // Whether the event is hidden to the consumer or not
“externalId”: “123221231”, // External ID provided by the POST event when you create a webhook
“category”: “DEVICE”, // Category of the event (device, zone, schedule)
“type”: “RAIN_DELAY”, // type of event (varies by Hook type)
“subType”: “RAIN_DELAY_ON”, // description of the type of event
“deviceId”: “15c388d3-ca86-4c49-96d1-de11c965988d”, // Controller ID
“eventDate”: 1520803848658, // date the event happend
“createDate”: 1520803848658, // date event was created
“lastUpdateDate”: 1520803848658 // date event was updated
}
For my server I’ve tried Werkzeug as the application. When the event happens on my controller I see the server callback fire but it comes across as a ‘GET’ not a ‘POST’. I’m not sure that is a result of using a WSGI framework or me not understanding the webhook format.
Anyway, would appreciate any help.
Thanks!
This is the best site I’ve found for testing webhooks, I’ve used it to test ours.
We need more documentation around the response from the different event types, until we’ve had a chance to do that registering event types and using a URL generated from the above site works quite well.
Good morning,
I’m developing the openHAB binding for the Rachio controllers. Using a Java servlet I have events / webhooks running. This is no problem in general, but lack of the JSON format makes debugging stretchy - you need to wait on special events before you could analyze the JSON string and see the event types + attributes. Rachio support promised that the V3 API documentation includes that information, but it does not, or at least I was not able to find it. Be ware: Rachio changed the V3 JSON format significantly compared to V2!
Currently I’m fighting with Rachio’s support of https-based webhooks. After turning on Jetty debugging I saw that the request is coming, but the certificate could not be validated. Jetty displays a “alert: certificate unknown”. I tried https://mqtt.rach.io in the browser, which has the same result. I saw that the chain is still including Symantec certificates, which are no longer valid and would explain the problem. However, Rachio support commented that tis URL is not used by the webhook interface?
So for the first steps make sure that you are using a http (not https) webhook. It supports a private port by adding :xxxx and a URI path (e.g. http://mydomain.com:xxxx/rachio-webhook). The servlet could be registered specifically for this URI. Make sure that your firewall is forwarding this request to your smart home device. Don’t know yet if the https callback URL also supports the :xxxx notation.
Questions to Rachio:
- Which certificate is used for the included certificate on the https call?
- What is the format of ALL event JSONs?
- Is there a reason why different timestamp formats are used in the JSON format?
- The JSON format contains many redundant information. Is there recommendation, which attributes to use?
Cheers, Markus
HTTP or HTTPS is supported. Re-tested and HTTPS works fine. The URL I used for this test was https://webhook.site/36ef370b-1c8c-44dc-a061-71e132ae5516 (screenshot included below).
Also updated the documentation a bit and put all of our supported webhook types and subtypes along with some sample JSON.
HTTPS sample endpoint:
Hi Franz,
thanks for the prompt response. I appreciate to get more info on the JSON format, this helps. Adding some context information would be nice (e.g. when is the event send - some of same are clear, some of them like OFFLINE_NOTIFICATION vs. OFFLINE not).
Do you have any idea why Jetty reports a certificate error. I see your example, but if the certificate chain is fine on the test environment it will accept the inbound https with the certificate.
For me it seems that there is something missing in my local keystore to allow struct validation by Jetty.
If I have some time 
Sorry I do not. We are using a simple Feign HTTP client to POST data.
hmm, could you provide an export of the certificate so I could import that in my local keystore - just for testing
The server is a micro-service behind a private subnet making simple HTTP POSTs, we are not hosting certificates.