Callback: service status change

This endpoint is implemented by the merchant platform. Header xmh-hmc-signature (algorithm in authentication §4.2). Success is HTTP 200 only; the errCode in the body is not parsed.

Pushed on every service-order state change.

• Method: POST (Content-Type: application/json)
• Codes and text: Policy states (serviceState / serviceStateDesc here; query uses policyStatus / policyStatusDesc / policyStatusDescEn)
• Rapid consecutive transitions each push one message; deduplicate on serviceOrderId + serviceState

For the full field reference see API reference · webhook serviceStateChanged. Do not send requests to the OpenAPI hosts.

Request examples:

{
    "platformOrderId": "6462084809006",
    "serviceOrderId": "20251010XPP3310437F8F86",
    "serviceType": "PP",
    "serviceState": 5,
    "serviceStateDesc": "Refunded",
    "eventTime": "2026-08-04T10:11:12+08:00"
}

{
    "platformOrderId": "6462084809007",
    "serviceOrderId": "20251010XSP3310437F8F87",
    "serviceType": "SP",
    "serviceState": 3,
    "serviceStateDesc": "Effective",
    "eventTime": "2026-08-04T10:15:30+08:00"
}

serviceState values (English by default)

serviceState	serviceStateDesc	Meaning
1	Uninsured	Not insured
2	Insured	Insured
3	Effective	Effective
5	Refunded	Refunded
7	Expired	Expired
8	Cancelled	Cancelled

Response:

HTTP 200 counts as received; non-200 is treated as failure and retried. The body does not need to contain errCode.

Remarks

• This callback and the “service activated” callback are independent: activation notices still go to the activated callback, while every service-order state change goes to this callback; integrate either or both as needed. When both are configured, the “effective” moment produces two pushes (activated callback + this callback with serviceState=3).
• Pushes follow “changes as they happen”: retries may deliver duplicates, so deduplicate on serviceOrderId + serviceState.
• Merchants normally do not receive serviceState=7 (Expired) on this callback.
• The callback URL is agreed in the shop onboarding config (openapiConfig.callEndpoints → openApiServiceStateChangeCallBack); shops without it configured receive no pushes.