简介/原理

智能运营的Webhook是一种灵活的API，它能够支持各种自研或第三方的推送服务、站内信系统、优惠券发放系统、短信通知服务等，以及任何可能需要触发的自动化行为。

通过简单的REST API集成开发，您可以迅速实现对智能运营系统内置触发机制之外的扩展支持。这种轻量级的对接方式，不仅能够快速响应业务需求，还能提高系统的灵活性和扩展性。

以下是接入Webhook的业务流程图：

Webhook Request（默认小批量合并模式）

注意，Request Body 是批量打包的：

Webhook 请求的 Request Body 部分是一个打包的 JSON LIST；
这是为方便批量处理，智能运营已经对用户触发做了小批量合并；
智能运营的 Webhook 在一个请求中包含了多个用户的触发；

Request 结构如下：

POST /your/path HTTP/1.1
Content-Type: application/json
Content-Length: 1000
Host: xxx
Connection: Keep-Alive
User-Agent: xxx

[{"msg_id": "123123123","params" : {"account_id"："账户号1","自定义字段1"："用户字段值1","自定义字段2"："事件字段值1"}},{"params" : {"account_id"："账户号2","自定义字段1"："用户字段值2","自定义字段2"："事件字段值2"}}]

Request Body 是一个 LIST：

[{
    "msg_id": "123123123",
    "params" : {
        "account_id"："账户号1",
        "自定义字段1"："用户字段值1",
        "自定义字段2"："事件字段值1"
    }
},{
    "params" : {
        "account_id"："账户号2",
        "自定义字段1"："用户字段值2",
        "自定义字段2"："事件字段值2"
    }
}]

Webhook Response

HTTP 200 无 Body，智能运营认为全部发送成功。

HTTP 200 有 Body，并返回详细的报错信息，您需要产生一个 Response Body 如下：

[
    {
        "succeed": true
    },
    {
        "succeed": false,
        "fail_reason": "....."
    },
    ...
]

Demo样例

对于 Java 开发者，我们提供了对 Webhook 协议的简单案例。

package com.hina.demo.controller;

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.hina.demo.model.HookMessageReq;
import com.hina.demo.model.HookMessageRes;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.ArrayList;
import java.util.List;
import java.util.Map;

@RestController
@RequestMapping("/hina/webhook")
public class WebhookController {

    private static final Logger log = LoggerFactory.getLogger(WebhookController.class);

    @PostMapping("/receive")
    public List<HookMessageRes> receive(@RequestBody List<HookMessageReq> req) throws JsonProcessingException {
        log.info("请求 receive 参数 {}", new ObjectMapper().writeValueAsString(req));
        // TODO 业务处理
        List<HookMessageRes> result = new ArrayList<>();
        for (HookMessageReq hookMessageReq : req) {
            // 业务处理 - 获取您配置的用户属性
            Map<String, String> userProfile = hookMessageReq.getUser_profile();
            for (Map.Entry<String, String> entry : userProfile.entrySet()) {
                log.info("用户属性 {} {}", entry.getKey(), entry.getValue());
            }
            // 业务处理 - 获取您配置的动态参数
            Map<String, String> params = hookMessageReq.getParams();
            for (Map.Entry<String, String> entry : params.entrySet()) {
                log.info("动态参数 {} {}", entry.getKey(), entry.getValue());
            }
            // 结果封装
            HookMessageRes hookMessageRes = new HookMessageRes();
            hookMessageRes.setSucceed(true);
            result.add(hookMessageRes);
        }
        log.info("响应 receive 结果 {}", new ObjectMapper().writeValueAsString(result));
        return result;
    }
}

Demo 代码包下载

至此您已经可以启动一个用于处理神能运营 Webhook 请求的服务。

在这里可以结合业务实现更复杂的代码逻辑，如将“用户信息写入数据库”、“给用户发放代金券”、“给用户推送站内信”、“基于数据发起一个新的对其他系统的 API 请求”等。