目录
此内容是否有帮助?

# Webhook Access Document

# Introduction

Webhook of the TE operation module defines an API whose purpose is to connect any message or message-like system on the downstream client.

Clients can quickly support a built-in trigger channel of the non-TE operation module through docking development of relatively lightweight REST API.

Refer to the following figure for the specific call link:

  1. First, the TE operation module will read event data and user data from Thinking Analytics (TA) to calculate the number of target audiences.
  2. According to the target audience and message content, the TE operation module will send a webhook request to one of your own HTTP webhook servers.
  3. After your own webhook server has received the request, you can convert the format, join other business data, enter the asynchronous processing queue and perform other tasks, and finally call any other internal or external message/message-like systems. Examples of systems that may be called:
  • Game mail system
  • Game announcement system
  • Account banning system
  • SMS system
  • Third-party push system
  1. Recovery of receipt event data
  • If data is pushed to the game mail system, then the mail opening event is reported in the mail of the game app, so that TA can get the push receipt event for subsequent analysis of conversion effect.

# Webhook server

To dock with Webhook of the TE operation module, you need to develop an HTTP Endpoint Server. See below for applicable API definition.

# Format definition of input and output parameters

# Webhook Request

The input parameters of the server are generated by the TE operation module. The POST method is used, and the Content-Type is set to application/json. request_body is a JSONArray, which supports sending multiple messages in one batch. Each message represents a message with a specific content sent to a user.

Examples of parameters are as follows:

// request input parameter format
[
    {"push_id":"3e156c91-f039-4d48-9b6f-72b76111af24","custom_params":{"gameuid":"123acb123","name":"Zhang San",...},"params":{"title":"daily activities",...},"ops_receipt_properties":{"ops_task_id":"0050",...}}
    {"push_id":"5c190470-d81e-4f8e-841a-fe19b95ae47a","custom_params":{"gameuid":"123acb123","name":"Li Si",...},"params":{"title":"daily activities",...},"ops_receipt_properties":{"ops_task_id":"0050",...}}
]

// specific input parameter format of each message
{
    //id Send id, push id of webhook
    "push_id": "3e156c91-f039-4d48-9b6f-72b76111af24",
    //template parameter, the specific parameter content under this parameter can be defined by 'TE operation module-channel management'
    "params": {
        "title": "daily activities",
        "content": "Hello, Zhang San, come and join the activity!",
        //array row
        "attachment": [{
            {
                "item_id":"xx1",
                "count":"5"
            },
            {
                "item_id":"xx2",
                "count":"10"
            }
        }]
    },
    //custom parameters can specify user properties. The specific parameter content under this parameter can be defined by 'TE operation module-channel management'
     "custom_params": {
         "gameuid":"123acb123",
         "name": "Zhang San"
    },
    //channel receipt property, this parameter is added by default by the TE operation module system for subsequent data statistics, and no analysis is required on the business side. It can be transparently transmitted to the downstream
    "ops_receipt_properties": {
        "ops_request_id": "f7b66eb7-3363-4a46-a402-601a64b45f76",
        "ops_task_id": "0050",
        "ops_task_instance_id": "31",
        "ops_project_id": 1
    }
}
Parameter name Parameter type Required (Yes/No) Parameter description Remark
push_id
 String
 Yes
 Push ID
 Specific parameter fields can be defined by 'TE operation module-channel management-push ID'
params
 Object
 No
 Template parameters
 Some channel parameters need to be filled in by the operator when pushing, such as pushed content.
Specific parameter content can be defined by 'TE operation module-channel management-template parameters'
custom_params
 Object
 No
 Custom parameters
 User properties of push target audiences need to be automatically generated by the system
Specific parameter content can be defined by 'TE operation module-channel management-custom parameters'
ops_receipt_properties
 Object
 Yes
 Receipt field of TE operation module
The TE operation module system is added by default
If the downstream system needs to observe the message CTR, this field needs to be transparently transmitted and reported directly in the click event
In conversion events, this field does not need to be reported

Template parameters, naming convention of custom parameter Key: names are split by underlines, parameters consist of letters, numbers and underlines, and the leading characters can only be underlines and letters

Note: In params and custom_params, for any type of data (such as integer, decimal and date), when sending requests, all fields are converted to strings for processing

# Webhook Response

Examples of parameters are as follows:

{
    "return_code": 0,
    "return_message": "success",
    "data": {
        // each element in the fail_list is the failed object information, including the error message and the serial number of the error object, and the serial number of the error object starts from 1. Assumed that 5 objects are sent and the serial number is 1-5, in which 3 succeeded and 2 failed and the 2nd and 4th objects failed, then the following are returned:
        "fail_list": [{
            "index": 2
            "message": "the player token information to be pushed does not exist",
        }, {
            "index": 4
            "message": "push id not found",
        }]
    }
}
Parameter name Parameter type Required (Yes/No) 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
 Return data
data.fail_list
 Array
 No
 If return_code=0,
data.fail_list is [] or null, all will be considered successful
If data.fail_list is not null, it is a partial failure, and the failure details are defined in the list.
Note: The index property of the object in the failure list represents the serial number, starting from 1, not from 0!
If no partial failure occurs in the business, just pass [] directly;
If return_code=1, no matter what is passed in data.fail_list, it will be considered as a failure.

# Request authentication

If webhook needs to support authentication, the server also needs to implement a signature verification logic. The sender will add the signature to the http header file, and the Key is X-TE-OPS-Signature.

The server needs to perform a HmacSHA1 signature on the key and the Request Body and generate a signature, and then compare it with the signature on the server. If it is found consistent through comparison, the authentication is passed.

The Java implementation of the signature algorithm is as follows:

import org.apache.commons.codec.digest.HmacAlgorithms;
import org.apache.commons.codec.digest.HmacUtils;
/*
   HmacSHA1 signature algorithm

   secretKeyYes key configured by the client
   requestBodyYes 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;
}

# Request concurrency

To ensure the message push speed, the higher the concurrency of the endpoint server, the better. At least 1000TPS is recommended.

# Request and result integrity test example

// request information
curl -X POST "http://localhost:8999/v1/hermes/webhook/test/sample"
-H "accept: */*"
-H "X-TE-OPS-Signature: 2e1ee1eeaDA121"
-H "Content-Encoding: gzip"
-H "Content-Type: application/json"
-d "[{\"push_id\":\"3e156c91-f039-4d48-9b6f-72b76111af24\",\"costom_params\":{\"name\":\"Zhang San\"},\"params\":{\"title\":\"daily activities\",\"content\":\"Hello, Zhang San, come and join the activity!\"},\"ops_receipt_properties\":{\"ops_task_id\":\"0050\",\"ops_request_id\":\"f7b66eb7-3363-4a46-a402-601a64b45f76\",\"ops_task_instance_id\":\"31\",\"ops_project_id\":1}}]"

// return result
{
  "data": {
      "fail_list": []
  },
  "return_code": 0,
  "return_message": "success"
}

# Introduction to configurable parameters of Webhook

Configuration item
 Optional value
 Default value
 Configuration description
 Productized (Yes/No)
Channel authentication
 Enabled, disabled
 Disabled
 To enable channel authentication, you need to provide a key, then the TE operation module will add the signature to the X-TE-OPS-Signature field in the Http header when requesting the webhook service, and provide it for downstream verification
 Yes
Request compression
 Enabled, disabled
 Enabled
 Set whether the http protocol needs to perform content compression
 No
Sending traffic limit
 -1，[1,10000]
 No traffic limit
 Unit: times/second
If it is set to -1, this means no traffic limit.
It is set to a number from 1-10000. If it is set to 500, this means the downstream webhook server accepts up to 500 requests per second.
 No
Size of sending batch
 [1,500]
 100
 It indicates the number of elements contained in the JsonArray of the parameters of one call
A large batch size can improve the efficiency of sending
A small batch size will slow down the sending speed, but the sending accuracy will be improved in extreme exceptions.
If the number of users is small and the push accuracy is required, the recommended value is 1
If the number of users is large (>500w) and the push speed is required, the recommended value is 100 and the maximum value is 500.
 No
Timeout
 -1，[0,3600]
 60
 Unit: second
After the timeout is set, the http request will have a timeout, and the status return value of the http request of the downstream server will be determined. The call is deemed successful only when status=200, otherwise the call is considered failed.
If -1 is set, it will not check whether it is timed out. Even if it is timed out, the call is considered successful
 No
Strict verification of return value
 Enabled, disabled
 Enabled
 After enabled, the TE operation module server will verify the format of the response returned by the downstream server. If it does not meet the above webhook response parameter definition specification, it will be considered a failure
Example: Suppose the timeout is set to 5s
If strict verification of the return value is disabled, the webhook server returns normally within 5 seconds, and the return value is HTTP 200 without Body. In this case, the TE operation module considers this call to be successful.
If strict verification of the return value is enabled, the webhook server returns normally within 5 seconds, and the return value is HTTP 200 without Body or the Body format is inconsistent with the convention specification. In this case, the TE operation module considers this call to be failed.
 No

# Example of channel configuration page

Parameter Description Remark
Channel name
 Webhook name (for display and selection)
 Uniqueness verification
Channel URL
 Interface address for receiving message push
 Support the same URL address with multiple channels
Send ID
 ID type of target audience who receives the message, for example, role ID (role_id) of the user used to send mail
 The send ID needs to be reported as a user property
When estimating the number of target audiences, users whose send ID is null will be filtered
Channel authentication
 webhook authentication method
 Optionally enabled. It currently supports Token keys
Reach funnel settings
 Name of meta event associated with funnel steps
 Optionally enabled
Content template
 Template of specific content sent to the user by this channel. It supports field types such as text, dynamic text, value, and array row. For example, the channel for sending mails can configure the item content (item ID and item quantity) by the array row type, which can be displayed on the front end of the reach task and filled in by the operation staff who configure the operation tasks
 Field: parameter name, used in the message body when sending
Field name: field displayed when creating a task
Field type: text, dynamic text, number, array row, etc.
Prompt: prompt in the input box when creating a task (optional)
Required: Yes/No (multiple choice, yes by default)
Custom parameters
 Optionally added according to channel requirements. This parameter is transparently transmitted
 Not required
Field: parameter name, used in the message body when sending
Associated field: user properties associated with the field. The field value is this property value when sending the message body
Default value: optional, default value is set. When the property value is null, the default value is used; if the default value is not set, a null value is returned when the property value is null

# Acquisition of click push events

Based on messages pushed through webhook, you can acquire click events on the client/server as needed. For the acquisition method, please refer to the method of reporting events in the data integration manual. The event name can be customized, and event data needs to be acquired from the ops_receipt_properties field in the message sent by webhook and all transparently transmitted.

Example codes:

JSONObject properties = new JSONObject();
//get ops_receipt_properties from the message body sent by webhook, and report it as ops_receipt_properties
properties.put("ops_receipt_properties",message.get("ops_receipt_properties"));
instance.track("ops_push_click",properties);

← Android Push Integration Document →