Home Assistant Core imou is documented as cloud polling, so do not treat its two-minute device/status refresh as an alarm webhook. For prompt alarms, an architecture option is to configure an internet-reachable Imou Open Platform HTTP callback, acknowledge valid deliveries quickly, and bridge sanitized events into Home Assistant. This bridge is an application recommendation, not a Core feature or an Imou delivery SLA.
Polling and push solve different problems
The Core integration page documents periodic polling for the device list and online status. Imou Open Platform separately documents server-to-server event message push. Polling provides refreshed state and discovery; callbacks provide an event-delivery path. A robust design may use both, but should not pretend that a callback automatically updates every Core entity.
Documented callback setup
setMessageCallback uses an administrator access token. With status on, the callback URL must be reachable from the Internet and callback flags are required. The current page lists alarm, deviceStatus, numberstat, and faceAnalysis categories and allows one or more comma-separated values. basePush currently documents 1 as push and 2 as no push. Recheck these live values before use.
Documented receiver behavior
The push guide says the developer backend receives platform messages and must return HTTP 200. It warns that when the callback service repeatedly fails to return a response, the platform will stop pushing to that address. The guide does not provide a retry count or backoff schedule on the cited page, so the bridge must not invent either.
Recommended bridge architecture
Architecture recommendation: terminate HTTPS at a small backend endpoint, validate requests according to the current event documentation, store a minimal idempotency record, return 200 promptly after safe acceptance, and publish a sanitized internal message. A Home Assistant automation can consume that message through a locally chosen mechanism. The transport from bridge to Home Assistant is your responsibility.
Implementation sequence
- Decide which documented callback categories are needed. 2. Build and externally test the HTTPS receiver. 3. Keep App Secret and administrator token outside Home Assistant dashboards and public YAML. 4. Call
setMessageCallbackfrom the trusted backend. 5. Confirm a known test event reaches the receiver. 6. Map only required fields into a Home Assistant event or helper. 7. Add reconciliation and health monitoring without claiming guaranteed delivery.
Home Assistant handoff options
Depending on the operator's existing stack, the bridge can call an authenticated Home Assistant webhook designed for a narrow payload, publish to an already secured message bus, or expose a local integration endpoint. These are Home Assistant architecture choices, not Imou-prescribed methods. Use network allowlists, narrow credentials, payload limits, and replay controls suitable for the selected handoff.
Quota consequences
The Home Assistant Core page says Open Platform API limits apply to the App ID and that polling usage grows with device count. The maintained component repository also warns that component API requests and video playback consume account resources. Push can reduce the temptation to poll rapidly for alarms, but it does not make normal integration polling, playback, or follow-up API calls free.
Failure handling
Alert on callback silence, non-200 rates, queue age, and Home Assistant handoff failures. Keep an operator action for rechecking callback configuration if push stops. Architecture recommendation: reconcile important event history through documented query surfaces where available. Do not describe that reconciliation as a guarantee that every event can be reconstructed.
Security pitfalls
Do not expose Home Assistant directly without a narrow authentication boundary, forward full callback bodies to notifications, trust an event solely because it reached a public URL, or log image URLs and tokens indefinitely. Apply rate limits and size limits. Review event formats rather than guessing signatures or fields not present in the current event documentation.
Community-oriented conclusion
If periodic status is sufficient, Core polling may be all you need. Add a callback bridge only for a clear automation requirement and only if you can operate a public receiver safely. Share redacted diagrams and reproducible behavior with peers; do not post callback secrets, App credentials, or device identifiers.
Verification discipline
Treat the linked live documentation as the boundary of the claim. Capture the page and review date in the release ticket, and recheck method names, fields, permissions, regions, and status values before publication. Console behavior and repositories can change after this draft. If the live source disagrees with this article, update the article rather than preserving an outdated assertion.
Secret handling
Keep App Secret values and administrator access tokens on a trusted backend. Do not place them in Home Assistant YAML shared publicly, browser bundles, mobile logs, screenshots, sample repositories, or support tickets. Redact device identifiers and live addresses in diagnostics. A live URL is operational data and should be distributed only through the authorization boundary designed by the application owner.
Capability and service boundaries
A documented platform method does not prove that every device, channel, account, or subscribed service supports the same outcome. Test with the actual account region and target device family. Present missing controls as a capability or service question first, then gather diagnostics, instead of promising universal behavior or inventing a model matrix.
Observability
Record the request ID, method, region, result code, and a redacted resource identifier for backend calls. Add timestamps around each stage so operators can distinguish local validation, platform rejection, device availability, and downstream delivery. Logs must never contain App Secret values, full administrator tokens, reusable live URLs, or unredacted callback payloads.
Rollout practice
Start with one test application, one account region, one device, and one channel. Validate the happy path and an intentional failure before expanding. A staged rollout makes region mistakes, quota pressure, unsupported capabilities, and stale credentials visible while the affected inventory is still small.
Architecture status
Unless a sentence is explicitly attributed to Imou or Home Assistant documentation, workflow choices in this article are recommendations, not platform guarantees. Queue design, caching, reconciliation, alert thresholds, and retry policy belong to the application operator. They should be tuned from measured behavior without being presented as an Imou SLA.
Change control
Put region, callback, credential, schedule, and integration changes through review. Record the old value, intended value, operator, validation request, and rollback condition. This is especially important where a seemingly small configuration edit can change cloud traffic or make an entire device group unavailable. Review current documentation again when applying a saved runbook.
Test evidence
A useful community or production report states what was tested without exposing private material: Home Assistant or application version, integration path, account region, method, device capability category, UTC time, and redacted result. Separate observed evidence from interpretation. That makes later maintenance possible even when repository releases or platform documentation have moved.
Exit criteria
Define success before rollout: the intended resource appears, one controlled action or event completes, resource use remains visible, and rollback has been rehearsed. Also test a wrong-region or unavailable-device case so support staff recognize the difference. Document only what the test proves, and leave unsupported device families or account configurations explicitly unresolved.
Keep the bridge optional: automations should degrade predictably when it is unavailable, and polling entities should not be misrepresented as confirmation that a push arrived. In community reports, distinguish callback receipt, bridge processing, and Home Assistant automation execution as three separate observations.
Official sources
Live-source review date: 2026-08-31. Recheck before publication.
Top comments (0)