Prize Information Submission Callback
Purpose
When a viewer wins a prize in a live stream lottery and successfully submits their prize claim information (shipping details), the server will send a POST request to the callback URL configured by the client. This allows the client system to synchronize business processes such as receiving and shipping orders.
Callback Failure Retry
- If the interface does not return an HTTP status 200, the callback is considered to have failed. In case of failure, the callback will be retried up to 3 times.
- A callback failure does not affect the viewer's ability to submit prize claim information.
Callback Parameter Description
- Request Method: POST
URL Parameters
| Parameter | Type & Range | Description |
|---|---|---|
| timestamp | long | 13-digit timestamp |
| sign | string | Signature generated using the rule MD5(appSecret + timestamp). To prevent forged callback requests, please verify the correctness of the sign value. The appSecret is the key of the live streaming system (viewable in developer settings). |
BODY Parameters:
| Parameter | Type & Range | Description |
|---|---|---|
| recordId | String | Prize ID (primary key of the prize record, uniquely identifying a prize record) |
| lotteryId | String | Lottery ID |
| channelId | Integer | Channel number |
| winnerTime | Long | Time of winning (13-digit millisecond timestamp) |
| viewerId | String | Winning viewer's user ID |
| viewerName | String | Winning viewer's nickname |
| winnerCode | String | Winning code |
| prize | String | Name of the prize |
| name | String | Name (extracted from prize claim information) |
| mobile | String | Phone number (extracted from prize claim information) |
| address | String | Address (merged field; province/city/district/town/street and detailed address are combined, extracted from prize claim information) |
| customFields | Object | All fields of the prize claim information, with key as field name and value as field value (including name, phone, address, and custom fields; field names are based on the backend lottery collection field configuration). name/mobile/address are extracted from this object by field name and match the corresponding field values, provided for convenient access. |
| groupNames | Array<String> | List of group names |
| presetEnabled | String | Whether the prize is preset (Y: Yes, N: No) |
Callback Data Example
Example Request URL: https://www.example.com/xxx/callback?sign=d5079f2e8ba19e49bfd3d9575866d80f×tamp=1701964858687
Example Request Body (body parameter: application/json)
{
"recordId": "zyNfUVnaAZ",
"lotteryId": "hjzf98qa0n",
"channelId": 8017543,
"winnerTime": 1782896361000,
"viewerId": "viewer123",
"viewerName": "张三",
"winnerCode": "hpbVp66y",
"prize": "二等奖",
"name": "张三",
"mobile": "13900000000",
"address": "广东省深圳市福田区XX街道XX号",
"customFields": {
"姓名": "张三",
"手机": "13900000000",
"地址": "广东省深圳市福田区XX街道XX号",
"备注": "尽快发货"
},
"groupNames": ["A组"],
"presetEnabled": "N"
}
Note:
name/mobile/addressare convenience fields extracted fromcustomFieldsby field name keywords, consistent with the corresponding field values incustomFields;customFieldsretains all prize claim fields, and it is recommended to usecustomFieldsas the primary source for values.- The field names in
customFields(e.g., "Name", "Phone", "Address") are based on the backend lottery activity's "Collection Fields" configuration. Custom field names are determined by the configuration.
How to Configure
Configure via the backend:
Log in to your account - Go to [Cloud Live] - Click [Developer Settings] - Click [Callback Settings] - Prize Information Submission Callback
Note: The submitted callback URL must start with http:// or https://. If no callback URL is configured, the callback will not be triggered.
