# 短信服务接口定义

URL: https://docs.ones.cn/admin/set-up-your-team/phone-and-sms-settings/sms-service-api

# 1.实现webhook连通性测试

为了保障数据安全，ONES需要对webhook的连通性以及token的有效性进行验证。webhook需要实现如下功能，以便保存webhook配置时进行验证。

调用方式：http/https

method :GET

query参数：echo_str=xxxxxxx

接口实现：echo_str是一个token为秘钥，使用AES-256-CBC加密的密文字符串，webhook需要对这段密文进行解密，回传给ONES。

接口返回：echo_str解密后的字符串。

# 2.按要求实现短信webhook

当ONES系统产生短信相关事件时，我们会按如下方式调用您所配置的短信webhook，您需要根据请求参数实现具体的发短信功能。

调用方式：http/https

method：POST

content-type：application/json

body：

```json
{
  "operation_user": "李华",
  "phone_numbers": "18812345678;18812345679",
  "message_type": "captcha",
  "summary": "标题",
  "action": "复制",
  "count": 3,
  "code": "123456",
  "timestamp": 1637739583,
  "sign": "90fbfcf15e74a36b89dbdb2a721d9aecffdfdddc5c83e27f7592594f71932481"
}
```

body参数说明：

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| operation_user | string | 操作者的名称 |
| phone_numbers | string | 接收方手机号列表，多个号码以";"分隔。 |
| message_type | string | captcha：短信验证码，notice：工作项通知，remind：工作项提醒，workflow：工作流通知，wiki：wiki通知 |
| summary | string | 标题 |
| action | string | 批量触发类型：复制、新建、编辑 |
| count | number | 批量触发数量：为0时代表非批量 |
| code | string | 验证码 |
| timestamp | number | 消息产生时的unix时间戳。 |
| sign | string | 请求签名，验证方法见第二步。 |

# 3.验证签名

我们通过签名机制来防止请求的伪造或篡改。签名方法如下：

```json
# 先拼接签名字符串
paramString = "operation_user=李华&phone_numbers=18812345678;18812345679&message_type=captcha&summary=标题&action=复制&count=3&code=123456×tamp=1637739583&token=xxx"
# 加上token
signString = paramString+"&token=xxxxxxxx" # token为配置webhook时填写的
# hmac-256签名
sign = hash_hmac("sha256", signString, token) # token为配置webhook时填写的
```

在收到webhook的调用后，需要根据接收到的参数和签名算法再算一次签名值，然后和参数中的sign值匹配。如果两者一样，则验证通过，如果不一样，则应该阻止这个请求。