Homey.webhooks' API is undefined/unavailable

Questions & Help
1

Hi everyone,

I’m trying to create an integration to control the brightness of a light group on my Homey Pro using the physical wheel on my Beoremote Halo.

The correct method for this seems to be using the Halo’s “Extensions” API, which sends an HTTP request (webhook) to Homey for each wheel turn. To receive this, I’m trying to create a webhook from within a HomeyScript.

The Problem

My issue is that the Homey.webhooks API seems to be completely unavailable on my Homey Pro (2023).

When I run a very simple test script to isolate the issue, it fails immediately. The script checks for the existence of Homey.webhooks and returns undefined .

Here is the minimalist test script I’m using:

// Minimalist test script
log('Starting simple Webhook test...');

async function runTest() {
  if (!Homey.webhooks) {
    log('❌ Critical Error: Homey.webhooks API is not available.');
    return;
  }
  log('✅ Webhooks API is available.');
  // ... rest of the creation logic
}

runTest();

The output is always: ❌ Critical Error: Homey.webhooks API is not available.

Troubleshooting Done:

  • I have confirmed I am running on a Homey Pro (2023) , not a Bridge.
  • I have rebooted the Homey Pro multiple times, but the issue persists.
  • I have confirmed that Flow webhooks work correctly . I can trigger a Flow from Postman without any issues. The problem is isolated to the Homey.webhooks API used by HomeyScript.

Has anyone else experienced this issue where the Homey.webhooks object is undefined on a Homey Pro? It seems like a core service is not running, and I’m looking for ideas before I contact Athom support directly.

Thanks for any help!

2

Why do you think Homey.webhooks should exist? Where is it documented?

3

Beacuse Gemini told me :joy:
Maybe I should let Gemini vacuum the documentation before trusting it blindly :wink:
But you’re telling me there’s no such thing?

4

Gemini, and other LLM’s (remember, they’re not “AI”, they’re glorified autocompletes), just make sh*t up as they go along :man_shrugging:t3:

No, there’s no such thing.

You can create webhooks, but only using the SDK, which means writing an actual app. You can’t use these API’s from HomeyScript.

But flow webhooks are probably much easier to use anyway, and will cover most use cases.

1 Like
5

Gemini is very persistent.

You are correct that for building a full Homey App, one would use the App SDK and the methods described in that part of the developer documentation.

However, I believe there is a separate, simplified API available specifically within the HomeyScript environment on the Homey Pro. I am referring to the Homey.webhooks object.

While it seems to be poorly documented on the main HomeyScript reference page, its existence and usage are confirmed by expert users and developers in various threads on this community forum. It appears to be a convenience wrapper provided by Athom to allow for simple, programmatic webhook creation directly from a script without needing to build and install a full app.

My core issue is that on my specific Homey Pro unit, the Homey.webhooks object is undefined , while for other users it seems to be a valid object with a createWebhook() method. This happens even after multiple reboots.

This strongly suggests that the problem is not that the API doesn’t exist, but rather that the service providing this API is failing to start correctly on my specific device.

This code is from Athom’s official documentation

const myWebhook = await this.homey.cloud.createWebhook(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);*
    });

You can find it here:
Webhooks | Homey Apps SDK

6

And btw @robertklep I don’t doubt your talent at all. I know you’re a huge contributor to the community and an excellent developer as well. I just want to make sure that there is no hidden gem somewhere that lets me use the suggested approach from Gemini :slight_smile:

Thank you again :folded_hands:

7

Would you use an undocumented feature?

8

Nope :slight_smile:

I’ll try to figure out another way to make it work :slight_smile:
Thank you for the reply :folded_hands:

9

You’re being gaslighted.

10

Why not doing it the easy way?

image
image1143×1338 77.5 KB

See documentation (found by googling Homey Webhook): https://support.homey.app/hc/en-us/articles/18292876827548-Using-Webhooks-with-Homey

11

I’ll see what I can do :slight_smile: