Document push subscription webhook commands - #3230
Conversation
Add register_push_subscription and remove_push_subscription to the native app integration webhook commands, so companion apps can subscribe to silent pushes on entity state changes. Documents the core feature added in home-assistant/core#174943.
📝 WalkthroughWalkthroughDocumentation update adding two new webhook action sections—"Register a push subscription" and "Remove a push subscription"—to the native app integration sending-data guide, describing payload fields, idempotency, limits, and required parameters. ChangesPush Subscription Documentation
Estimated code review effort: 1 (Trivial) | ~5 minutes Related PRs: None specified Suggested labels: documentation Suggested reviewers: None specified 🐇 A quiet hop through docs anew, 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/api/native-app-integration/sending-data.md`:
- Around line 353-358: The parameter tables in the native app integration doc
need to be reformatted to match the repo’s markdownlint style, since the current
no-leading-pipe layout will keep failing MD055/MD058. Update both the
subscription table and the removal table using the same leading-pipe table style
used elsewhere in the guide, and ensure each table is separated by blank lines
before and after it. Use the existing table sections in the sending-data
markdown as the targets for this formatting cleanup.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: a0ad7a44-c9c9-412f-9d30-ac8f93188183
📒 Files selected for processing (1)
docs/api/native-app-integration/sending-data.md
| | Key | Type | Description | ||
| | --- | ---- | ----------- | ||
| `subscription_id` | string |Stable identifier the app assigns to this subscription. Re-registering with the same value updates the existing subscription in place. Required. | ||
| `push_token` | string | The token the push should be delivered to. Required. | ||
| `entity_ids` | list | Entity IDs whose state changes trigger a push. Must contain between 1 and 50 valid entity IDs; duplicates are ignored. Required. | ||
| `target` | string | Opaque value echoed back in the push payload so the app can route it to the correct surface. Optional. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Normalize both parameter tables to the repo’s markdownlint style.
Both tables use the no-leading-pipe format and need blank-line separation, so they’ll keep triggering MD055/MD058 in docs CI. Please switch them to the leading-pipe style used elsewhere in the guide.
Suggested fix
+
+| Key | Type | Description |
+| --- | --- | --- |
+| `subscription_id` | string | Stable identifier the app assigns to this subscription. Re-registering with the same value updates the existing subscription in place. Required. |
+| `push_token` | string | The token the push should be delivered to. Required. |
+| `entity_ids` | list | Entity IDs whose state changes trigger a push. Must contain between 1 and 50 valid entity IDs; duplicates are ignored. Required. |
+| `target` | string | Opaque value echoed back in the push payload so the app can route it to the correct surface. Optional. |
+Apply the same formatting to the removal table below.
Also applies to: 372-374
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 353-353: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
[warning] 355-355: Table pipe style
Expected: leading_only; Actual: no_leading_or_trailing; Missing leading pipe
(MD055, table-pipe-style)
[warning] 356-356: Table pipe style
Expected: leading_only; Actual: no_leading_or_trailing; Missing leading pipe
(MD055, table-pipe-style)
[warning] 357-357: Table pipe style
Expected: leading_only; Actual: no_leading_or_trailing; Missing leading pipe
(MD055, table-pipe-style)
[warning] 358-358: Table pipe style
Expected: leading_only; Actual: no_leading_or_trailing; Missing leading pipe
(MD055, table-pipe-style)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/api/native-app-integration/sending-data.md` around lines 353 - 358, The
parameter tables in the native app integration doc need to be reformatted to
match the repo’s markdownlint style, since the current no-leading-pipe layout
will keep failing MD055/MD058. Update both the subscription table and the
removal table using the same leading-pipe table style used elsewhere in the
guide, and ensure each table is separated by blank lines before and after it.
Use the existing table sections in the sending-data markdown as the targets for
this formatting cleanup.
Source: Linters/SAST tools
hariharanjagan
changed the title
2 participants
Proposed change
Documents two new webhook commands the companion app can send to Home Assistant:
register_push_subscriptionandremove_push_subscription.An app registers a push token together with a list of entity IDs it wants to
watch. When any of those entities changes state, Home Assistant posts to the
app's push URL so the app can refresh. Re-registering with the same
subscription_idupdates the existing one (for example when the token or theentity list changes). The second command removes a subscription.
Both are added to the existing list of webhook commands on the
Sending data page, following the same format as the other commands.
Type of change
Checklist
Additional information
Summary by CodeRabbit