Definition
Webhook When events such as device online/offline, alarm triggers, or OTA completion occur, the platform sends an HTTP POST request to the URL configured by the user to push event data. It is used for integration with ITSM, Work Order, and self-built systems, triggered by Rule Engine.
Configuration and Security
The Webhook requires configuring a target URL, request method (usually POST), and optional request headers (such as signatures or authentication Tokens). It supports HMAC signature verification, allowing the receiver to verify the source of the request based on the signature. It is recommended to use HTTPS, configure retry strategies (such as exponential backoff), and set timeouts to ensure push reliability. In case of failure, logs can be recorded, alerts triggered, or messages routed to a dead-letter queue for manual handling.
Event Types
Common events include: device online/offline, property changes, event reporting, alarm triggers, OTA task status changes, device registration/deletion, etc. The Webhook payload typically includes event type, timestamp, device identifier, and related data. The receiver can parse the payload to create Work Orders, sync to ITSM, trigger business logic, or write to a data warehouse.
Comparison with OpenAPI
Webhooks are pushed proactively by the server, suitable for real-time, event-driven scenarios; OpenAPI is pulled actively by the client, suitable for batch queries and configurations. They complement each other: Webhooks handle event notifications, while OpenAPI handles data retrieval and operations, together forming the platform's open capabilities.
A push is an at-least-once event notification
An event push answers "tell the other side when something has happened." It does not hand the other side a full archive they can use as a database. On an agreed event, the platform sends a request to the receiving address. The body carries an event identifier, a type, the time it occurred, and the related device. When the network times out or the other side fails briefly, the platform retries according to policy, so the same event can arrive more than once. That is at least once, not exactly once. If the receiver does not deduplicate, one alarm becomes several records.
A push does not guarantee that order is strictly kept across all events. After retries in particular, a later event can be received successfully first. The receiver should order by the time and the identifier inside the event. It cannot assume that whatever arrived later is the update. Put identifiers and a summary in the payload. Let the other side pull a large historical curve through the API by identifier. Stuffing a whole stretch of telemetry into every push amplifies traffic when a failed attempt is retried, and it makes both the signature and the timeout unstable.
The receiver must be able to deduplicate by event identifier
The condition for use is that the receiver stores event identifiers it has seen for a recent period. When one arrives again, it returns already-processed and does not run the business action again. The platform generates the identifier and keeps it unchanged across retries. If the receiver manufactures an identifier from arrival time, it cannot recognize a retry as the same event. Deduplication records should be kept longer than the platform's maximum retry window. Otherwise a retry in the second half of the window is treated as a new event.
Signature checks finish before business parsing. Verify, with the shared secret or the public key in the platform documentation, that the body was not altered. On a failed check, reject the request. Do not enter the success path that retries depend on. The address must be an endpoint the receiver controls, and the transport must be encrypted. On the platform side it should be possible to disable a subscription and to see recent response codes, but the other side's internal address must not be hardcoded into configuration that cannot be rotated. When a trace is required, write the result of each attempt to the audit log, including the failure reason, rather than recording a line only when it finally succeeds.
Returning success before processing is finished
If the receiver returns success as soon as the request arrives, and then writes the work order slowly in the background, a background failure leaves the platform believing the event was delivered, and it will not try again. A success response should mean "this event identifier has been recorded durably, and processing can continue even if the process restarts." Processing itself may be asynchronous, but the recording step has to finish first. A response that is too slow triggers a platform timeout and a retry. Together with deduplication that is safe: the first attempt did record it, and the second is recognized as a duplicate.
Driving a field action that must not be repeated directly from a push is dangerous in the same way. A retry or more than one subscription makes the action run more than once. The push only notifies. The field action runs on a control path that carries a command identifier. A subscription that is too wide is another common problem. Pushing every property change buries the receiver in periodic telemetry, and the real alarm is inside that stream. A subscription should limit event type and device range, and it should be narrowed when the receiver cannot keep up, rather than piling failed requests without limit into the platform retry queue. A long-running failure on the other side should enter a dead letter and alert the subscriber. It must not be dropped silently, and it must not be retried without a cap until it fills the send capacity.
The subscription configuration should state the retry count, the interval, and the condition under which the last failure enters the dead letter. A dead letter must be replayable by event identifier, and the replay must keep the original identifier, so the receiver's deduplication still holds. If the replay mints a new identifier, the other side runs the business action again. The sender records the status code and the duration of each response, but it does not record the full key or the signature material. When the receiving address changes, verify the new address with a test event first, then cut the production subscription over. Keep the old address until in-flight retries finish. Deleting the old address suddenly makes every retry already sent fail and flood the dead letter. Test events and production events use different type marks. When the receiver sees the test mark, it records connectivity only. It does not create a formal record, and it does not count toward the business total after deduplication.