I’m trying to create an automation that’s triggered by accessing a URL on my Home Assistant instance. Looking at the Webhook Trigger section of Automations > Triggers, that looks like what I want.
But I can’t for the life of me find any actual documentation about how to create a webhook.
Searching here in the community turns up lots of results, none of which have gone into any details about how to create and use a webhook. Most don’t really seem to be about webhooks at all, at least not HA webhooks.
Webhooks aren’t an integration, there’s nothing to setup to enable webhooks. When building an automation if you choose the webhook trigger then you just have to enter an ID in the box. Once you do, you’ll be able to trigger that automation by sending an unauthenticated HTTP POST request to {your HA URL}/api/webhook/{the ID you entered}. You can also optionally provide a postbody in JSON or encoded form data and that will be available in templates in the conditions and actions of your automation as described in the doc.
@firstof9 Not correct. That’s the doc I was starting from. It shows up in the results, too. But I already know about that part, triggering an automation from a webhook. What I’m trying to learn is, how do you create a webhook in the first place? That’s not what the result you pointed at is about.
@CentralCommand Are you saying that, there’s no way to define a webhook, that (effectively) ALL POSSIBLE webhooks are implicitly defined already?
That is, the act of listening for a webhook with a given ID (by putting it into a trigger) causes the webhook to become real, and Home Assistant will automatically handle it?
@firstof9 So, webhooks are implicitly defined, by the very act of listening for them (via adding to a trigger)?
That seems like madness, or maybe mad genius.
But it also seems like something that could be explained more clearly. I’ll submit a revision PR tomorrow. (I’ve had a couple drinks this evening, so PR-ing seems like a dangerous activity…)
Effectively yea. Technically its always listening at /api/webhook/* since it believes anything that comes next is a webhook ID. If you have registered a listener for that webhook ID then it calls that when a request comes in. If you don’t then you just see this in your log:
2020-04-18 22:39:53 WARNING (MainThread) [homeassistant.components.webhook] Received message for unregistered webhook jsafpoiwjpoeighjawgjwlj
You can try it out pretty easily in Postman or curl by just making a call to an unregistered webhook endpoint like that and then registering it with an automation.
Honestly I didn’t really think to much about it at the time but I suppose you’re right, it is kind of odd. I was personally more bothered by the fact that they accepted unauthenticated requests which made me inclined to avoid them. You have to use them for IFTTT integration but at least no one can snoop that URL by being on the same wifi.
The point is to make them extremely specific in purpose so that authentication isn’t really necessary but still, its not my favorite feature. Although I noticed today when looking in my Nginx Proxy Manager logs that it looks like there’s a ton of webhook traffic coming in from the HA Android Mobile app. I didn’t even know this was happening so now I’m wondering what other secret webhooks are active…
Considering how much of a pain in the neck it is to define or change a webhook in some other automation systems, this was a breath of fresh air to me when I first started with HA. I think being able to define them on the fly and change the name on the fly is awesome.