Implementing setMessageCallback: Make Imou Events Reach a Public HTTPS Endpoint

Subscribe from a trusted backend with an administrator accessToken by calling setMessageCallback. Set status to on, provide an internet-reachable callbackUrl, pass only currently documented callbackFlag values, and set basePush using the live page (1 push, 2 no push). Your handler must return HTTP 200 quickly. Then read the stored configuration with getMessageCallback and test a real supported event. Do not invent extra flags or retry counts.

Why it matters

Saving a URL in a ticket is not a subscription. Wrong flags, a private laptop URL, TLS problems, or a handler that times out before 200 can all produce silence. Implementation work is therefore: public HTTPS receiver, documented flags, administrator call, verification read, and a fast ack with asynchronous processing.

Approach / architecture

Administrator backend
  -> setMessageCallback(status=on, callbackUrl, callbackFlag, basePush)
  -> getMessageCallback (verify stored values)
Device / platform
  -> HTTPS POST to callbackUrl
  -> your receiver returns 200
  -> queue
  -> product workflow

Field	Documented job
status	on or off
callbackUrl	Public URL the platform can reach
callbackFlag	Comma-separated categories from the live page
basePush	1 push / 2 no push; default documented as 2

Current setMessageCallback documentation lists alarm, deviceStatus, numberstat, and faceAnalysis. Recheck that list before you ship; it is not a promise that every device emits every category.

Seven implementation steps

1. Deploy a public HTTPS endpoint. Use TLS. Reject oversized bodies. Do not place this route on a developer machine or a VPC-only service without a documented ingress path.

2. Persist then acknowledge. Parse enough to enqueue an idempotent job, return HTTP 200, then process. Slow downstream work before 200 is a common cause of later silence. Exact retry/backoff counts are not published; do not invent them.

3. Select flags from the live page only. Example for alarms plus online/offline: alarm,deviceStatus if those values still appear in documentation. Do not map a msgType to a flag by guesswork.

4. Set basePush explicitly. Do not assume it duplicates callbackFlag.

5. Call setMessageCallback with an administrator token. When status is on, current docs require callbackUrl and callbackFlag.

6. Read back with getMessageCallback. Compare stored URL and flags with what you intended.

7. Prove one real event path. Use a device and feature that can actually produce the category. Log message family and request correlation without dumping secrets or raw personal images into shared logs.

APIs / SDKs

• setMessageCallback
• getMessageCallback
• Push process — HTTP 200 requirement; repeated failure can stop pushes
• Event format — payloads differ; many alarms have no image array

Queuing, idempotency, and dead-letter handling are application architecture recommendations, not a platform completeness guarantee.

Limits & pitfalls

• Unreachable URL, redirects, and auth walls on the callback all look like “no events.”
• Returning 4xx/5xx or hanging the handler can stop delivery after repeated failure.
• Not every event includes picUrlArray.
• Administrator credentials stay on the backend.
• Recheck flags and the 200 rule on publication day.

Receiver design that stays honest

Build the callback service as a dumb, fast edge: TLS termination, body size limit, schema check, enqueue, 200. Everything that talks to your user-notification stack belongs behind the queue. If you authenticate the callback, use a method you can operate (reverse proxy allowlists, shared HMAC you rotate, or mTLS). Do not require a browser cookie. Do not block on sending email or writing to a data warehouse before 200.

Idempotency keys should come from fields that are stable in the payload family you actually receive. Because event shapes differ, do not assume a single alarmId exists on deviceStatus messages. Store the raw body in a restricted bucket if you need forensics; store a redacted projection in the application database. Image URLs, if present, are sensitive. Encrypted alarm images are not JPEGs; decryption belongs in the documented client/component path, not in ad hoc scripts committed with keys.

After setMessageCallback, keep a runbook: getMessageCallback output, last 200 timestamp, last non-200, and whether the platform still appears to be pushing. If pushes stop, fix reachability and 200 behavior first, then re-subscribe if the stored URL is gone. Do not document a retry count you did not read on the live push page.

Load-test the receiver with synthetic POSTs that look like production, but do not claim those tests equal Imou delivery. Device capability still gates whether an alarm flag produces a message at all.

Environment parity matters. Staging must use a public URL the platform can reach, not localhost. Use a separate developer application if you cannot risk production callback overwrites: setMessageCallback stores one subscription for the developer account on current docs, so a shared appId between staging and production will fight over the same callback URL. Confirm that account-level behavior on the live page before you share credentials across environments.

Document the owner of the receiver (which team, which cloud account, which certificate). Expired TLS is a silent-callback incident. Certificate automation is your operations work, not an Imou feature.

Implement the receiver first, then configure it with live setMessageCallback from Imou Open Platform and verify the stored subscription before you depend on alarms in production.