Events

Once customers assets have been onboarded onto partner's platform, since then we start to exchange events to control and validate the device's behavior.

This section of the guide details how you should send events to HanchuESS Connect. In it you will find out how the endpoint should beimplemented, how to manage subscriptions to our webhook service.

Depends on you

In order to receive the telemetry and control events from the HanChuESS Connect, you will need refer to Subscriptions API and build the same mechanism, after that, we will use below endpoint to do subscription, hence we could receive data with the following headers and request body from partner.

Events endpoint

When you need send control event, the endpoint should be a POST endpoint with a path like the following:

Example - https://idaas-sandbox.hanchuess.com/api/{YOUR_IDENTIFY}/v1/events

Request body

The body should be of content type application/json and may contain batch of events for a number of different assets and different event types. A full list of events that can be reveived are listed in Send and Receive scenarios.

Rule

• Data array must NOT exceed either 100 items.

• Payload as a whole must not exceed 10 MB.

• All timestamps must be in UTC ISO8601 format.

• If there is a corrupt item within the data array, the rest of the items must still be processed and the corrupt item should be raised with the relevant development team.

{
    "timestamp": "2024-01-01T00:00:00.000Z",
    "data": [
        {
            "type": "{EVENT-TYPE}",
            "timestamp": "2025-07-01T11:00:00Z",
            "assetId": "H01****5X1H7Z",
            "data": {
                ...   
            }
        },
        { ... }
    ]
}

Subscription secret

No matter who would do subscription, always generate a cryptographically-secure secret which will be persisted on server. The secret will be shared with us using the subscription endpoint when the webhook is set up.

We will use the secret to generate a signature on each event we send to each other. The secret should be a pseudo-random value of at least 128 bits produced byasecure generator.

Generating a payload signature

Requests will bear an X-Signature header, verify it before we start to handle business.

The signature is the HMAC hex digest of the payload, as following:

• algorithm = sha256

• key = provided during webhook subscription

• payload = The request body

See Signature for more details.

payload is UTF-8 encoded string containing JSON - not to deserialize it before signature computation.

Retries

If HanchuESS Connect receives a non-2XX response when sending events, it will retry up to four times with exponential backoff, starting at 2 minutes:

• 1st retry: 2-minute delay

• 2nd retry: 4-minute delay

• 3rd retry: 5-minute delay

After the third attempt, HanchuESS Connect will stop sending the telemetry. If repeated failures exceed a certain threshold, the subscription will be deactivated, and the partner will be alerted. Once the partner restores their service, they must test their subscription to reactivate it.