Build a Reliable Imou Event Pipeline: Callbacks for Latency, Queries for Completeness

Use Imou callbacks as the low-latency ingestion path, then run scheduled getAlarmMessage queries as an application-level reconciliation path for supported alarm records. Persist first, process asynchronously, deduplicate with stable event identifiers, and operate retries, dead letters, and monitoring yourself. This callback-plus-query design is architecture guidance—not an Imou guarantee of complete, exactly-once, or gap-free delivery.

Why It Matters

Real event systems fail at boundaries: a callback returns late, a deployment rejects a payload, a worker crashes after writing one table but before sending a notification, or an image disappears before retrieval. A durable pipeline should make each boundary observable and recoverable without claiming semantics the platform does not document.

Imou documents callback delivery and a query interface. Combining them for reconciliation is a prudent design choice. The platform pages do not state that every callback event is queryable, that query results contain every push family, or that the two paths together guarantee completeness.

Architecture

                         +----------------------+
Imou callback ----------> callback ingress     |
                         | persist raw + 200    |
                         +----------+-----------+
                                    |
                                    v
                              durable event log
                                    |
              +---------------------+--------------------+
              |                     |                    |
              v                     v                    v
          normalizer            image worker        notifier
              |                     |                    |
              +---------- retries / dead letter --------+
                                    ^
                                    |
scheduled getAlarmMessage ----------+
  per authorized device/channel/time window
  application-level reconciliation

Separate documented behavior from recommendations:

Item	Status
Configure a callback with setMessageCallback	Documented Imou interface
Receiver returns HTTP 200	Documented requirement
Repeated missing responses can stop pushes	Documented warning
Query alarm records with getAlarmMessage by device, channel, time range, and pagination	Documented interface
Combine callbacks and queries to reconcile gaps	Recommended application architecture
Idempotency keys, deduplication windows, queues, dead letters, alerts, SLOs	Your application’s design and operations
Exactly-once or complete delivery	Not claimed here; no such guarantee is cited

Implementation Steps

1. Build a minimal callback ingress. Validate transport and a bounded body, preserve the raw event, enqueue durable work, and return HTTP 200. Do not wait for image downloads, tenant joins, or customer notifications.
2. Create an immutable event ledger. Store source (callback or query), receive time, platform event time, device/channel identity as provided, event type, raw payload hash, normalized status, and processing history.
3. Define idempotency by payload family. A general push example includes id; queried alarms include alarmId. Prefer documented stable identifiers within the appropriate family. When none is documented, use a conservative composite or payload hash and record the collision policy. This rule is yours, not a platform uniqueness promise.
4. Normalize through versioned adapters. General alarms use fields such as did, cid, and msgType; other families can use deviceId, channelId, or different bodies. Keep raw data so adapter changes are replayable.
5. Run reconciliation only where the query contract applies. getAlarmMessage queries device alarm records for a device channel and time interval. It accepts administrator or suitably authorized sub-account tokens and paginates with nextAlarmId. Do not use it as proof that status, sharing, traffic, heatmap, or every intelligent event can be reconstructed.
6. Use overlapping time windows. Query a small overlap around the last successful watermark, then deduplicate. This recommendation tolerates clock and job-boundary uncertainty; choose overlap based on observed operations, not an invented Imou SLA.
7. Retry workers, not ingress acknowledgement. Classify transient retrieval or downstream errors, cap application retries, and move unresolved records to a dead-letter queue for inspection. No platform retry count is assumed.
8. Monitor every stage. Track callback HTTP status and latency, persisted events, queue age, adapter failures, reconciliation discoveries, duplicate rate, dead-letter count, image failures, and end-user notification latency.

Reconciliation Details

The documented getAlarmMessage request includes token, deviceId, channelId, beginTime, and endTime. It allows count from 1 to 30 and uses nextAlarmId for pagination. Query each authorized device/channel scope and continue until the page sequence is exhausted according to the live interface documentation.

Use administrator credentials only on a trusted backend. If a reconciliation worker uses a sub-account token, the interface page identifies minimum Alarm permission on the cam:serial number:channel number resource. Recheck permissions on the live page and ensure the worker cannot cross tenant boundaries.

Reconciliation can discover alarm records not present in your callback ledger. Insert them with source query, pass them through the same idempotent normalizer, and alert on a sustained increase. It can also return a record already received by callback; that is expected in this architecture and should become a deduplication hit, not a second user notification.

Do not require exact structural equality between push and query. Push examples and query results have different field names and purposes. Link records using documented identifiers where available and preserve uncertainty instead of forcing a false match.

APIs and Official Sources

• Event message push process: callback flow, HTTP 200 requirement, and warning about stopping after multiple missing responses.
• setMessageCallback: configures callback state, URL, and categories.
• Event message format definition: documents multiple push payload families and a general alarm id.
• getAlarmMessage: queries alarm records, documents alarmId, time range, page size, nextAlarmId, token types, and minimum sub-account permission.
• Device alarm message module: describes alarm-message query and delete operations.

Limits and Pitfalls

Callbacks are not an exactly-once contract. Make consumers idempotent and expect duplicates or reprocessing in your own pipeline.

Queries are not a universal event replay API. getAlarmMessage covers its documented alarm records. Do not claim it reconstructs online/offline, account lifecycle, passenger-flow, heatmap, or every AI event.

HTTP 200 is not “all downstream work completed.” It means your callback endpoint met the documented response requirement. Your durable write should establish responsibility before acknowledgement.

Deduplication can erase real events if keys are too broad. Device plus minute plus type is usually unsafe. Prefer documented IDs and retain raw hashes and provenance.

Time windows need explicit timezone handling. Store UTC-normalized internal timestamps while constructing requests exactly as the current interface requires. Test daylight-saving transitions for device-local displays.

Images are optional and may require decryption. Do not fail the event because picUrlArray is absent. Queue applicable media promptly and use official decryption components.

Dead letters need ownership. A queue with no alert, retention, replay tool, or runbook is merely hidden data loss. Define an operator and replay procedure.

Monitoring thresholds are yours. Do not label internal targets as Imou SLA or platform guarantees.

Suggested Operational Checks

• Callback success rate specifically counts HTTP 200.
• Callback p95 latency excludes worker processing because work is queued.
• Event-ledger insert failures page an operator.
• Reconciliation watermark age is visible per device/channel shard.
• “Found by query but not callback” is measured by event family.
• Duplicate suppression records the selected key and source pair.
• Dead-letter entries retain redacted payloads and actionable error classes.
• Replay is idempotent and cannot notify customers twice.
• Credentials and signed image URLs are redacted from all telemetry.

Register at Imou Open Platform to evaluate its cloud-video and AIoT callbacks, alarm-query APIs, and SDKs, then validate this recommended pipeline against your devices, regions, and operational requirements.