Webhook Documentation


#16

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


#17

@markus7017

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:


#18

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.


#19

If I have some time :wink:

Sorry I do not. We are using a simple Feign HTTP client to POST data.

:cheers:


#20

hmm, could you provide an export of the certificate so I could import that in my local keystore - just for testing


#21

The server is a micro-service behind a private subnet making simple HTTP POSTs, we are not hosting certificates.

:cheers:


#22

Does the platform supports webhooks via https? I see the incoming request, which then fails due to a certificate problem.


#23

Yes. Use https://webhook.site for testing.

:cheers:


#24

Hi @franz, after a while I just tried to use https and it just works :slight_smile:
Are there new certificates installed on the Rachio side? Otherwise may be a problem with my test environment


#25

The server is a micro-service behind a private subnet making simple HTTP POSTs, we are not hosting certificates.

:cheers:


#26

@franz My openHAB binding is working very stable in between. I want to add support to retrieve the zone pictures from the Rachio cloud and make them available to a html widget. The corresponding url is returned as part of the configuration information (get person) - imageUrl.

In the past the imageUrl contained the base URI as well as a unique identifier.

During my last tests I always got only the base URL. I verified the JSON returned by the cloud
…“imageUrl”:"https://prod-media-photo.rach.io/"
which is missing the uniqie id compared to
…“imageUrl”:“https://prod-media-photo.rach.io/daf89bd1-0744-4603-a5b4-32218fceaae6” of early tests. Other testers are reporting the same issue, so it’s not specific to my installation.

I also noticed that some of the standard icons/pics are not located on https://prod-media-photo.rach.io/, but AWS like: https://s3-us-west-2.amazonaws.com/rachio-api-icons/nozzle/fixed_spray.png

Do you have any idea why the unique id for imageUrl is missing?


#27

I see what happened. This issue should be resolved tomorrow.

:cheers:


#28

I could confirm that the imageUrl is working again.

This brought to the following problem: If you try to embed those images to a simple html view it will fail. The browser downloads a file rather than displaying a image when you open this url.

From my understanding the mime type is not set. This should be fixed. I found a work around in rewriting the url and redirecting load requests to my binding, which loads the image from the cloud as binary and sends it as response with mime-type image/png. That works, but I think Rachio should fix the implementation.


#29

Interesting, I’ll have the team look into it.

:cheers:


#30

my work around

  • take the imageUrl provided by the cloud api, strip off the uuid
  • rewrite the image url to a local servlet/uuid
  • the servlets reads the url as binary stream and writes it to the client, but also sets the mime-type
    in this case the servlet acts like a proxy and the html client/browser is happy :slight_smile:

#31

Hi @franz any update here? I would like to remove the work around if the cloud API works as expected (open the provided imageUrl in the browser and the image gets displayed rather than downloaded to a file). Putting my work around in changes provides exactly this change, but the cloud api should work http(s) compliant.


#32

On the App I received a notification about skipping watering. However, I don’t received a webhook event like WEATHER_INTELLIGENCE_SKIP even I registered for those:
[{“id”:“xxxxxxxx-b8bc-47a1-xxxxxxxx”,
“url”:“https://mydomain.com/rachio/webhook”,
“eventTypes”:[
{“name”:“ZONE_STATUS”,“type”:“WEBHOOK”},
{“name”:“DELTA”,“type”:“WEBHOOK”},
{“name”:“SCHEDULE_STATUS”,“type”:“WEBHOOK”},
{“name”:“DEVICE_STATUS”,“type”:“WEBHOOK”},{“name”:“WEATHER_INTELLIGENCE”,“type”:“WEBHOOK”},
{“name”:“RAIN_DELAY”,“type”:“WEBHOOK”},
{“name”:“ZONE_DELTA”,“type”:“WEBHOOK”}
]]

How to catch those events (in fact all)?


#33

New images have the correct mime-type. This week we will be updating existing images with the correct mime-type. Thanks for pointing this out. The new images now with directly from the URL.

I’ll have the team look into this.

:cheers:


API - Rain Skip Alert
#34

@franz Do you have an update for me?


#35

@franz I’m still very interested to integrate those events :slight_smile: