Webhook channel integration guide
1. Introduction
The Webhook channel of the AE Engage module defines an API for connecting to any downstream messaging or message-like system on the customer side. With lightweight REST API integration development, customers can quickly support trigger channels that aren't built into the AE Engage module. The following diagram shows the call chain:
- First, the AE Engage module uses event data and user data from the AE platform to calculate the target audience.
- It then assembles the message content for the target audience. The AE Engage module sends HTTP requests in batches to the webhook channel service that you configure.
- After your own webhook channel service receives the HTTP call and gets the request content, it can perform operations such as format conversion, combining other business data, and adding to an asynchronous processing queue, and finally call any other internal or external messaging/message-like system. Examples of systems that may be called:
- Game mail system
- Game announcement system
- Account ban system
- SMS system
- Third-party push system
- After processing is complete (excluding asynchronous processing), return the processing result of the request in the agreed format. If any data failed to be processed, explicitly return the sequence number of that data and the reason for the failure. The AE Engage module records the data that failed to be processed.
- Receipt event collection (optional)
- If messages are pushed to the game's mail system, you can add tracking when the user opens a game mail, use "Click mail" as the tracking event for the Clicked step, and include the relevant passthrough parameters as agreed. This enables a more accurate Funnel Analysis of the delivery stage.
2. Webhook channel service
To integrate with the Webhook channel of the AE Engage module, you need to develop an HTTP Endpoint Server that follows the API definition below.
2.1 Request and response format
Webhook channel request
The input parameters of the service are constructed by the AE Engage module and sent with the POST method, with Content-Type set to application/json. The request body request_body is a JSONArray, so multiple messages can be sent in one batch. Each message represents a message with specific content sent to one user.
Note that one request body from the Webhook channel of the AE Engage module contains triggered messages for multiple users. This makes batch processing easier downstream and improves sending efficiency. The number of users in a batch can be configured.
The following is a parameter example:
// Request parameter format
[
{"push_id":"accountid123987001","custom_params":{"gameuid":"123acb001","name":"Zhang San",...},"params":{"title":"Daily Event",...},"#ops_receipt_properties":{"ops_task_id":"0050",...}}
,{"push_id":"accountid123987002","custom_params":{"gameuid":"123acb002","name":"Li Si",...},"params":{"title":"Daily Event",...},"#ops_receipt_properties":{"ops_task_id":"0050",...}}
]
// Parameter format of each message
{
//Push ID of the channel, usually the user's unique ID, such as the account ID or character ID. Defined by operators in 'AE Engage module - Channel Management'
"push_id": "accountid123987001",
//Template parameters. The specific parameters under this parameter can be defined in 'AE Engage module - Channel Management'
"params": {
"title": "Daily Event",
"content": "Hi Zhang San, come and join the event!",
//Array Row
"attachment": [
{
"item_id":"xx1",
"count":"5"
},
{
"item_id":"xx2",
"count":"10"
}
]
},
//Custom parameters, which can carry user properties. The specific parameters under this parameter can be defined in 'AE Engage module - Channel Management'
"custom_params": {
"zone_id":"17281",
"name": "Zhang San"
},
//Channel receipt properties. This parameter is added by the AE Engage module by default for subsequent data statistics. Usually your business side doesn't need to parse it; just pass it through downstream. When reporting downstream, report this JSON object directly; don't convert it with toString before reporting
"#ops_receipt_properties": {
"ops_project_id": 1, //AE project ID
"ops_task_id": "0050", //Corresponds to an operation task; included only for operation task pushes
"ops_task_instance_id": "0050_2023-01-01", //Corresponds to an operation task instance; included only for operation task pushes
"ops_task_exec_detail_id": "17795", //Corresponds to one push of a task instance; included only for operation task pushes
"ops_request_id": "f7b66eb7-3363-4a46-a402-601a64b45f76", //Corresponds to one batch request in a push. All ops_request_id values in the same request are identical, and this ID doesn't change when the request is retried. If your business system needs to perform idempotency checks on requests, use this field. Included only for operation task pushes.
"ops_exp_group_id": "122", //A/B test group ID of the operation task; included only when the operation task has an A/B test enabled
"ops_flow_id":"0050", //Corresponds to a journey; included only when delivered by an action node of a journey
"ops_flow_version":"V_20251010_1", //Journey version number; included only when delivered by an action node of a journey
"ops_node_id":"1001", //Journey node ID; included only when delivered by an action node of a journey
"ops_push_language": "default" //Push language; included for multi-language pushes
}
}
| Parameter name | Parameter type | Required | Description | Remarks |
|---|---|---|---|---|
| push_id | String | Yes | Push ID | Define the specific parameter field in Settings - Channel Management - Push ID |
| params | Object | No | Template parameters | Channel parameters that operators fill in when pushing, such as the push content. Define the specific parameters in Settings - Channel Management - Content Template |
| custom_params | Object | No | Custom parameters | User properties of the push target users that the system brings in automatically. Define the specific parameters in Settings - Channel Management - Custom Parameters |
| #ops_receipt_properties | Object | Yes | AE Engage module receipt field | Added by the AE Engage module by default. If downstream systems need to observe message clicks, pass this field through directly when reporting the click event. You don't need to report this field in the conversion event set in the task goal |
Naming convention for the keys of template parameters and custom parameters: Use underscore-separated names. Parameters consist of letters, digits, and underscores, and can start only with an underscore or a letter. Note: In the params and custom_params parameters, data of any type (such as integers, decimals, and dates) is converted to strings when the request is sent
Webhook channel response
The following is a parameter example:
{
"return_code": 0,
"return_message": "success",
"data": {
// Each element in fail_list contains information about a failed object, including the error message and the sequence number of the failed object. Sequence numbers start from 1. For example, if 5 objects are sent with sequence numbers 1-5, 3 succeed and 2 fail, and the 2nd and 4th fail, the following is returned
"fail_list": [{
"index": 2,
"message": "The token of the player to push doesn't exist"
}, {
"index": 4,
"message": "push id not found"
}]
}
}
| Parameter name | Parameter type | Required | Parameter description |
|---|---|---|---|
| return_code | Integer | Yes | Return code. 0 means success (or partial success). 1 means failure |
| return_message | String | No | Return message |
| data | Object | No | Returned data |
| data.fail_list | Array | No | If return_code=0:
If return_code=1, all objects are considered failed regardless of what is passed in data.fail_list. |
2.2 Request authentication
After this step is configured, you can enable it on the Webhook channel page in the product.
Authentication is disabled by default. If the Webhook channel server doesn't require authentication, skip this section. To support authentication, turn on the authentication switch when you configure the channel. The sender adds the signature to the HTTP request header with the key X-TE-OPS-Signature. The server needs to generate a signature by signing the Request Body with the secret key using HmacSHA1, and then compare it with the sender's signature. If they match, authentication succeeds. Reference Java implementation of the signature algorithm:
import org.apache.commons.codec.digest.HmacAlgorithms;
import org.apache.commons.codec.digest.HmacUtils;
/*
HmacSHA1 signature algorithm
secretKey is the secret key configured by the customer
requestBody is the JSONString of the request content
*/
public static String HmacSHA1(String secretKey,String requestBody) throws Exception {
String signature = (new HmacUtils(HmacAlgorithms.HMAC_SHA_1,secretKey)).hmacHex(requestBody)
return signature;
}
Reference PHP implementation of the signature algorithm:
/**
* HmacSHA1 signature algorithm
* @param $secretKey : Secret key configured by the customer
* @param $requestBody : JSONString of the request content
* @return string Signature value
*/
function HmacSHA1($secretKey, $requestBody) {
return hash_hmac('sha1', $requestBody, $secretKey);
}
2.3 Request concurrency performance
To ensure message push speed, the higher the concurrency the Webhook channel service supports, the better. We recommend supporting more than 100 TPS. In addition, the Engage module of AE can configure rate limiting according to the maximum concurrency of the downstream Webhook channel service.
2.4 Complete request and response test example
// Request
curl -X POST "http://localhost:8999/v1/webhook_channel/test/sample"
-H "accept: */*"
-H "X-TE-OPS-Signature: 2e1ee1eeaDA121"
-H "Content-Type: application/json"
-d "[{\"push_id\":\"3e156c91-f039-4d48-9b6f-72b76111af24\",\"custom_params\":{\"name\":\"Zhang San\"},\"params\":{\"title\":\"Daily Event\",\"content\":\"Hi Zhang San, come and join the event!\"},\"#ops_receipt_properties\":{\"ops_task_id\":\"0050\",\"ops_request_id\":\"f7b66eb7-3363-4a46-a402-601a64b45f76\",\"ops_task_instance_id\":\"31\",\"ops_project_id\":1}}]"
// Response
{
"data": {
"fail_list": []
},
"return_code": 0,
"return_message": "success"
}
3. Configurable parameters of the Webhook channel
The following parameters are configured in the backend by default. To modify them, contact ThinkingAI Customer Success
| Config items | Valid values | Default value | Description |
|---|---|---|---|
| Send rate limit | -1，[1,10000] | Unlimited | Unit: requests/second. Set it to -1 for no rate limit. Set it to a number from 1 to 10000, such as 500, to send at most 500 requests per second to the downstream Webhook channel server. |
| Send batch size | [1,500] | 100 | The number of elements in the JsonArray of the parameters in one call. A larger batch size improves message sending efficiency; a smaller batch size makes sending slower but more reliable. We recommend 100. The maximum is 500. |
| Timeout | [0,3600] | 60 | Unit: seconds. Socket timeout of HTTP requests. The default is 60s. If set to <=0, there is no timeout. |
| Failure retries | [0,10] | 0 | To avoid duplicate pushes, the default is 0, meaning no retry. If a value >0 is configured, the retry logic runs when the API times out or returns return_code!=0. |
| Retry interval on failure | [0,600] | 5 | Unit: seconds. Retries every 5s by default. |
| Strict response validation | Enabled, Disabled | Enabled | After this is enabled, the AE Engage module validates the format of the response returned by the downstream server. If it doesn't conform to the Webhook channel response parameter specification above, the call is considered failed. Example: Assume the timeout is set to 5s. If strict response validation is disabled, and the Webhook channel service returns normally within 5s with HTTP 200 and no body, the AE Engage module considers the call successful. If strict response validation is enabled, and the Webhook channel service returns normally within 5s with HTTP 200 and no body, or the body format doesn't match the agreed specification, the AE Engage module considers the call failed. |
4. Channel configuration page example
| Parameter | Description | Remarks |
|---|---|---|
| Channel Name | Name of the Webhook channel (for display and selection) | Must be unique |
| URL | URL of the API that receives message pushes | Multiple channels can use the same URL |
| Push ID | Type of target user ID that receives messages. For example, mail sending uses the user's character ID (role_id) | The push ID must be reported as a user property. When the audience size is estimated, users whose push ID is empty are filtered out |
| Custom request headers | Custom HTTP request headers attached when requests are sent, used to pass Authorization, an API Key, or a business identifier | Off by default. Turn it on as needed. Up to 10 headers. Header names are case-insensitive |
| Channel authentication | Custom channel authentication method | Off by default. Turn it on as needed |
| Funnel Setting | Event names associated with funnel steps | Optional |
| Content Template | Template of the content that this channel sends to users. Supported field types include Text, Dynamic text, Number, and Array Row. For example, a mail channel can use the Array Row type to configure item content (item ID and item quantity), which is shown on the frontend page of delivery tasks for the operators who configure operation tasks to fill in | Name: Name of the parameter, used in the message body when sending. Display name: The field shown when creating a task. Input Method: Text, Dynamic text, Number, Dropdown Selection, Date, Time, Array Row. Default Value: Optional. Enter it after you select the input method. Description: Hint shown in the input box when creating a task (optional). Required: If selected, the field is required. Not selected by default |
| Custom parameters | Add these as required by the channel. These parameters are passed through | Optional. Name: Name of the parameter, used in the message body when sending. Associated Property: The user property associated with the field. When the message body is sent, the field value uses this property's value. Default Value: Optional. If a default value is set, it is used when the property value is empty. If no default value is set, an empty value is returned when the property value is empty |
5. Collect push click events
For messages pushed through the Webhook channel, you can collect click events on the client or server as needed. For how to collect them, see the event reporting methods in the ThinkingAI data integration manual. The event name can be customized. The event data needs to get the #ops_receipt_properties field from the message delivered by the Webhook channel and report it as a whole as an object property. If you have other analysis scenarios, you can also add other properties to this event. Note: The property name must be #ops_receipt_properties and its type must be object. Don't change them. Changing the field name, modifying the content inside the field, or mistakenly reporting the field as a text property will all cause problems when the data is used later Code example:
JSONObject properties = new JSONObject();
//Get the JSON ops_receipt_properties object from the message body delivered by the Webhook channel, and report it as a whole as an object property
JSONObject opsReceiptProperties = message.get("#ops_receipt_properties");
//Note: The property name must be #ops_receipt_properties and can't be changed. The event name can be customized
properties.put("#ops_receipt_properties",opsReceiptProperties);
//Example of the properties object content: "#ops_receipt_properties":{"ops_task_id":"0062","ops_project_id":2,"ops_task_instance_id":"62","ops_request_id":"967ea854-2c42-490b-9c33-c1792ea637ec"}
instance.track("ops_push_click",properties);