Where are webhooks documented?

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 the Integrations list turns up nothing:

Searching the docs generally turns up nothing useful:

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.

What am I doing wrong in my searching?

It would be the 2nd result in your search there under “Automation Trigger” “Webhook trigger”.

1 Like

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.

The only documentation I’ve seen for webhooks is the webhook trigger section in the documentation on automation triggers. Although googling now also turned up this short guide on nabu casa’s site

5 Likes

@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.

That is how you create a webhook.

1 Like

@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?

1 Like

@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…)

I too thought it was weird and I had gone down the same rabbit hole, but alas you just setup an automation. :man_shrugging:

At least you can setup webhooks without having to restart Home Assistant :smiley:

2 Likes

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…

2 Likes

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.

I was surprised how easy it was, my comment at the time as, “that is it?”. :slight_smile:

Thanks to everyone for their answers, especially @firstof9 and @CentralCommand. PR for some doc updates submitted.

2 Likes

Hi guys, I’m trying to use webhook to trigger event from my camera (motioeye) but can’t get it working:

alias: 'Auto Terace Lights '
description: Automaticaly switch light on terace from terace ptz camera motion notification
trigger:
  - platform: webhook
    webhook_id: terace
condition:
  - condition: time
    after: '18:00'
    before: '09:00'
action:
  - service: switch.turn_on
    target:
      entity_id: switch.terrace_lights
  - delay:
      hours: 0
      minutes: 5
      seconds: 0
      milliseconds: 0
  - service: switch.turn_off
    target:
      entity_id: switch.terrace_lights
mode: restart

and in motioneye I have done:
image
where address is: https://myhomeassistant:8123//api/webhook/terace

Time is 05:00 AM
Why is it not working?

Could it be the misspelled webhook_id? In your trigger, you named it “terace”. Is that what you named it in motioneye?

Named the same, link I showed above…

Did you try to trigger via curl, to find out if the issue is in HA or motioneye?

no I didn’t, could you tell me how to do that? I’m running HASSOS

To do what? Send a curl?
There are examples on the webhook doc

If your issue is with curl itself, any way to send an HTTP POST command will do, e.g. Postman

Is there a way to listen for a webhook event in Dev Tools?
image

No. It’s not an event.
Webhooks are purely used in automations.