jeans/developers.home-assistant
jeans/developers.home-assistant
1
0
Fork 0
mirror of https://github.com/home-assistant/developers.home-assistant.git synced 2025-07-23 01:06:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

Document delivering webhooks over WS (#1180)

Browse Source
This commit is contained in:
Paulus Schoutsen 2022-01-24 04:52:57 -08:00 committed by GitHub
parent f8b349ad3a
commit 938ee76929
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 34 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
docs/api/native-app-integration/sending-data.md
View File

@ -4,6 +4,8 @@ title: "Sending data home"
Once you have registered your app with the mobile app component, you can start interacting with Home Assistant via the provided webhook information.
## Sending webhook data via Rest API
The first step is to turn the returned webhook ID into a full URL: `<instance_url>/api/webhook/<webhook_id>`. This will be the only url that we will need for all our interactions. The webhook endpoint will not require authenticated requests.
If you were provided a Cloudhook URL during registration, you should use that by default and only fall back to a constructed URL as described above if that request fails.
@ -16,6 +18,38 @@ To summarize, here's how requests should be made:
2. If you have a remote UI URL, use that to construct a webhook URL: `<remote_ui_url>/api/webhook/<webhook_id>`. When a request fails, go to step 3.
3. Construct a webhook URL using the instance URL provided during setup: `<instance_url>/api/webhook/<webhook_id>`.
## Sending webhook data via WebSocket API
Webhooks can also be delivered via the WebSocket API by sending the `webhook/handle` command:
```json
{
"type": "webhook/handle",
"id": 5,
"method": "GET",
// Below fields are optional
"body": "{\"hello\": \"world\"}",
"headers": {
"Content-Type": "application/json"
},
"query": "a=1&b=2",
}
```
The response will look as follows:
```json
{
"type": "result",
"id": 5,
"result": {
"body": "{\"ok\": true}",
"status": 200,
"headers": {"Content-Type": response.content_type},
}
}
```
## Short note on instance URLs
Some users have configured Home Assistant to be available outside of their home network using a dynamic DNS service. There are some routers that don't support hairpinning / NAT loopback: a device sending data from inside the routers network, via the externally configured DNS service, to Home Assistant, which also resides inside the local network.