Webhooks

Some web services use webhooks to notify clients something has changed, for example a thermostat's target temperature button has been pressed by the user. A webhook is simply a HTTP request sent to a pre-defined endpoint with some event-related data.

However, because Homey is connected to a LAN network, which is usually behind a firewall or NAT router, these webhooks cannot reach Homey directly. Athom Cloud can serve as a proxy in this case.

Creating a webhook

Your webhook consists of two parts: a cloud-component, and an app-component. Go to https://developer.athom.com/webhooks and click New Webhook.

Name

This is a name for your webhook, and is only used for your own reference.

ID

This ID is automatically generated, and should be used in your /env.json.

Secret

This secret is automatically generated, and should be used in your /env.json.

Cloud function

This function is a sandboxed piece of JavaScript that decides which webhook should be forwarded to which Homey. Both the homey_data object (as provided in CloudWebhook) and and webhook_data (as provided by the webhook's server) are available.

Simply return true to forward the webhook, or return false to reject it. This code is run for each registered Homey.

Registering a Homey to your webhook

In Homey, make sure to have a file /env.json with the following properties:

/env.json

{
  "WEBHOOK_ID": "<your_id>",
  "WEBHOOK_SECRET: "<your_secret>"
}

Then, register the webhook in your App:

/app.js

const Homey = require('homey');

let id = Homey.env.WEBHOOK_ID;
let secret = Homey.env.WEBHOOK_SECRET;
let data = {
  id: 'abcdef'
}

let myWebhook = new Homey.CloudWebhook( id, secret, data );
  myWebhook
    .on('message', args => {
      this.log('Got a webhook message!');
      this.log('headers:', args.headers);
      this.log('query:', args.query);
      this.log('body:', args.body);
    })
    .register()
    .then(() => {
       this.log('Webhook registered!');
    })
    .catch( this.error )

Firing the webhook

This is usually done by a 3rd party service, but to illustrate our example, let's assume that the following request is made:

POST https://webhooks.athom.com/webhook/56512fd03944692c0a3715da/?id=abcdef

This would result in the following args object in the app, and webhook_data on the server:

// args
{
  "headers": {
    // ...
  },
  "query": {
    "id": "abcdef"
  },
  "body": {}
}

Alternatively, if the following webhook was fired:

POST https://webhooks.athom.com/webhook/56512fd03944692c0a3715da/?id=987654

Then the webhook would not trigger the app's message event, because webhook_data.id (987654) is not equal to homey_data.id (abcdef).