开发指南

1. 简介

本指南旨在帮助开发者在自有服务器上快速搭建 Webhook 消息接收服务，以便实时获取并处理简道云通过数据推送发出的表单数据。指南涵盖服务端接口的推送方式、签名验证和响应规则，并提供了代码示例。无论您使用何种开发语言或技术栈，均可参照本指南完成对接，实现简道云与自由系统之间的数据互通。

2. 开发步骤

2.1 推送方式

简道云目前仅支持 POST 请求，请求参数如下所示：

代码示例如下所示：

POST http://example.com/jdy/hook?timestamp=1498586609&nonce=0f5ade
Headers: {
    "X-JDY-Signature": "72d3162e-cc78-11e3-81ab-4c9367dc0958",
    "X-JDY-DeliverId": "sha1=7d38cdd689735b008b3c702edd92eea23791c5f6"
}
{
    op: "data_create",
    data: {}
}

2.2 签名验证

为了防止 webhook 的接收服务器被第三方恶意攻击，用户在开发回调接口时，建议对回调请求进行签名校验，以确保回调请求来源来自于简道云。hook 会以 POST 的形式、将内容以 JSON 格式发送给指定地址。具体步骤如下所示：

1）在界面上随机生成一个 secret 或者自己指定一个 secret，并保存。这样，数据推送时就会把加密前的内容和通过secret加密后的内容一起推送到指定地址。

2）把 http 请求体字符串作为 payload，将其和 secret，请求参数里的 nonce、timestamp 按照 “{nonce}:{payload}:{secret}:{timestamp}” 的形式（用冒号分隔），组合为校验字符串 signature。

3）以 utf-8 编码形式计算 signature 的 sha-1 散列。

4）将 signature 散列的十六进制字符串与 POST 请求 header 中的 ‘X-JDY-Signature’ 做比较，若比较结果相同，则通过签名验证；若比较结果不同，则无法通过检查。

以 Python 为例，代码如下所示：

def get_signature(nonce, payload, secret, timestamp):
    content = ':'.join([nonce, payload, secret, timestamp]).encode('utf-8')
    m = hashlib.sha1()
    m.update(content)
    return m.hexdigest()

@app.route('/callback', methods=['POST'])
def callback():
    payload = request.data.decode('utf-8')
    nonce = request.args['nonce']
    timestamp = request.args['timestamp']
    if request.headers['x-jdy-signature'] != get_signature(nonce, payload, 'test-secret', timestamp):
        return 'fail', 401
    threading.Thread(target=handle, args=(json.loads(payload), )).start()
    return 'success'

2.3 响应规则

1）简道云向对应目标服务器推送请求后，该服务器需在 2 秒内使用 2xx 作为响应的状态码进行响应，即认为数据推送成功。

2）一次推送重试最多 5 次，如果单次推送连续重试 5 次均失败，则该次推送失败，此时会记录该数据在失败记录里，当连续失败达到 100 次时，该推送功能将被关闭，管理会获得消息通知，则需要管理员在推送设置中重新启动推送。

3. 代码示例

简道云为您提供了 Webhook server 多语言 调用示例，您可通过参考以下代码示例完成开发：

4. 注意事项

1）webhook推送错误说明

接收到推送后需要返回给简道云 2xx 表示推送接收成功。其他的返回结果则为返回信息错误，用户可以根据 HTTP 状态码自行定义推送错误的情况给简道云的返回码，简道云接受后，可在推送日志中显示出。

2）开发注意点

由于我们会对接口做各种扩展，为了保证每个对接的应用服务接收到更多样的推送数据时，不出现异常。所以请在接收到更多的 op 参数的数据类型时，直接响应成功，不要响应为失败。