Java如何通过钉钉机器人发送消息？

Question

**问题描述：** 在使用Java通过钉钉机器人发送消息时，开发者常遇到“webhook URL无效”或“签名失败”的错误。如何正确配置Webhook URL和签名参数？是否必须启用加签验证？如果不启用，是否存在安全风险？此外，发送的消息内容格式是否符合要求（如文本、链接、Markdown等），是否遗漏了必要的字段，也会导致发送失败。理解这些常见问题的根源，有助于快速定位并解决消息发送异常的情况。

Answer 1

一、问题背景与常见错误

在使用Java通过钉钉机器人发送消息时，开发者常遇到“webhook URL无效”或“签名失败”的错误。这些错误通常源于Webhook URL配置不正确、签名参数未按规范生成、消息格式不符合要求等问题。

• webhook URL无效：可能由于URL拼接错误、密钥过期、权限未开启等原因导致。
• 签名失败：加签验证机制未正确实现，如签名算法错误、时间戳不一致等。

二、Webhook URL的正确配置方式

钉钉机器人创建后会提供一个基础的Webhook URL，例如：

https://oapi.dingtalk.com/robot/send?access_token=your_token

如果启用了加签功能，则需要在URL中追加sign参数：

https://oapi.dingtalk.com/robot/send?access_token=your_token×tamp=xxx&sign=xxx

其中timestamp和sign必须动态生成。

三、签名参数的生成逻辑

签名生成流程如下：

1. 获取当前时间戳（单位：毫秒）作为timestamp。
2. 将timestamp拼接上自定义的加签密钥（secret），形成待加密字符串。
3. 使用HMAC-SHA256算法进行加密，并将结果Base64编码得到签名值。

Java示例代码如下：

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.Base64;

public class DingTalkSignUtil {
    public static String getSignature(String secret, long timestamp) throws Exception {
        String stringToSign = timestamp + "\n" + secret;
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(secret.getBytes("UTF-8"), "HmacSHA256"));
        byte[] signData = mac.doFinal(stringToSign.getBytes("UTF-8"));
        return Base64.getEncoder().encodeToString(signData);
    }
}
    

四、是否必须启用加签验证？

虽然钉钉允许不启用加签验证直接发送消息，但出于安全考虑，建议始终启用加签机制。以下是对比分析：

是否启用加签	优点	缺点	适用场景
否	配置简单，无需处理签名逻辑	存在被恶意调用的风险	内部测试环境或非敏感业务
是	增强安全性，防止伪造请求	需维护密钥并编写签名逻辑	生产环境或对外暴露的系统

五、消息内容格式与字段校验

钉钉支持多种消息类型，如文本、链接、Markdown、ActionCard等。每种类型都有严格的JSON结构要求。

以文本消息为例，其标准格式为：

{
    "msgtype": "text",
    "text": {
        "content": "这是一条测试消息",
        "mentioned_list": ["@all", "user123"]
    }
}
    

若缺少msgtype或对应类型的必填字段，将导致发送失败。

六、整体流程图与排查思路

从开发到发送的完整流程可表示如下：

graph TD
A[初始化Webhook URL] --> B{是否启用加签?}
B -- 是 --> C[生成timestamp]
C --> D[生成sign签名]
D --> E[拼接完整URL]
B -- 否 --> E
E --> F[构建消息体]
F --> G{消息格式是否合法?}
G -- 是 --> H[发送POST请求]
G -- 否 --> I[返回格式错误]
H --> J{响应状态码是否200?}
J -- 是 --> K[发送成功]
J -- 否 --> L[检查token权限、IP白名单等]