diff --git a/docs/api/native-app-integration/sending-data.md b/docs/api/native-app-integration/sending-data.md index ea2dbb18..881a1143 100644 --- a/docs/api/native-app-integration/sending-data.md +++ b/docs/api/native-app-integration/sending-data.md @@ -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: `/api/webhook/`. 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: `/api/webhook/`. When a request fails, go to step 3. 3. Construct a webhook URL using the instance URL provided during setup: `/api/webhook/`. +## 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.