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-18 14:56:28 +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. 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. 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. 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. 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>`. 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 ## 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. 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.