钉钉 Webhook 消息推送完全指南 | 极客日志

编程语言Node.js

钉钉 Webhook 消息推送完全指南

钉钉 Webhook 机器人的使用方法，对比了插件与 Webhook 的区别。文章重点讲解了@用户功能的原理及 JSON 配置要求，提供了 Shell、Node.js 和 Python 三种语言的完整推送脚本示例。此外，还涵盖了自定义关键词设置、手机号准确性检查、发送频率限制等避坑指南，帮助开发者实现稳定的钉钉消息通知功能。

SparkGeek发布于 2026/4/5更新于 2026/4/178 浏览

钉钉 Webhook 完全指南

一、基础知识

Webhook vs 插件

方式	优点	缺点
OpenClaw 插件	集成简单，双向通信	只能回复，不能主动发
Webhook 机器人	支持主动推送，格式丰富

格式	插件	Webhook
纯文本	✅	✅
Markdown	✅	✅
链接卡片	❌	✅
按钮卡片	❌	✅
@ 用户	❌	✅

{
  "msgtype": "text",
  "text": {
    "content": "【紧急通知】@所有人 请立即查看"
  },
  "at": {
    "isAtAll": true
  }
}

{
  "msgtype": "text",
  "text": {
    "content": "【任务分配】@手机号 请跟进项目进度"
  },
  "at": {
    "atMobiles": ["手机号"],
    "isAtAll": false
  }
}

{
  "msgtype": "text",
  "text": {
    "content": "@手机号 @手机号 请查看"
  },
  "at": {
    "atMobiles": ["手机号", "手机号"],
    "isAtAll": false
  }
}

#!/bin/bash
# dingtalk-notify.sh - 支持 @ 用户的钉钉推送
#
# 用法:
#   ./dingtalk-notify.sh "消息内容"          # 普通发送
#   ./dingtalk-notify.sh "消息内容" all      # @所有人
#   ./dingtalk-notify.sh "消息内容" lin      # @指定用户
#   ./dingtalk-notify.sh "消息内容" lin maple # @多人

MESSAGE="$1"
shift

if [ -z "$MESSAGE" ]; then
  echo "用法: $0 \"消息内容\" [all|用户名...]"
  exit 1
fi

# ===== 配置区域 =====
WEBHOOK_BASE="你的 Webhook 地址"
SECRET="你的加签密钥"

# 用户手机号映射
declare -A USERS
USERS["lin"]="手机号"
USERS["琳琳"]="手机号"
USERS["maple"]="手机号"
USERS["鸿枫"]="手机号"
# ===== 配置结束 =====

# 生成时间戳和签名
timestamp=$(date +%s%3N)
string_to_sign="${timestamp}\n${SECRET}"
sign=$(echo -ne "${string_to_sign}" | openssl dgst -sha256 -hmac "${SECRET}" -binary | base64 | sed 's/+/%2B/g; s/\//%2F/g; s/=/%3D/g')

# 构造 @ 参数
IS_AT_ALL="false"
AT_MOBILES=""
AT_TEXT=""

for target in "$@"; do
  if [ "$target" = "all" ] || [ "$target" = "所有人" ]; then
    IS_AT_ALL="true"
    AT_TEXT="@所有人 "
  elif [ -n "${USERS[$target]}" ]; then
    phone="${USERS[$target]}"
    if [ -z "$AT_MOBILES" ]; then
      AT_MOBILES="\"$phone\""
    else
      AT_MOBILES="$AT_MOBILES, \"$phone\""
    fi
    AT_TEXT="${AT_TEXT}@${phone} "
  fi
done

# 构造完整消息
FULL_MESSAGE="${AT_TEXT}${MESSAGE}"

# 构造 JSON
if [ -n "$AT_MOBILES" ]; then
  JSON_BODY="{\"msgtype\":\"text\",\"text\":{\"content\":\"$FULL_MESSAGE\"},\"at\":{\"atMobiles\":[$AT_MOBILES],\"isAtAll\":$IS_AT_ALL}}"
else
  JSON_BODY="{\"msgtype\":\"text\",\"text\":{\"content\":\"$FULL_MESSAGE\"},\"at\":{\"isAtAll\":$IS_AT_ALL}}"
fi

# 发送请求
curl -s "${WEBHOOK_BASE}&timestamp=${timestamp}&sign=${sign}" \
  -H "Content-Type: application/json" \
  -d "$JSON_BODY"

const crypto = require('crypto');
const axios = require('axios');

// 配置
const WEBHOOK_BASE = '你的 Webhook 地址';
const SECRET = '你的加签密钥';

// 用户手机号映射
const USER_PHONES = {
  'lin': '手机号',
  '琳琳': '手机号',
  'maple': '手机号',
  '鸿枫': '手机号'
};

/**
 * 生成钉钉签名
 */
function generateSign(secret, timestamp) {
  const stringToSign = `${timestamp}\n${secret}`;
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(stringToSign);
  return encodeURIComponent(hmac.digest('base64'));
}

/**
 * 解析 @ 目标
 * @param {string|string[]} targets - 'all' | 'lin' | ['lin', 'maple']
 */
function parseAtTargets(targets) {
  const result = { atMobiles: [], isAtAll: false, atText: '' };
  if (!targets) return result;

  const list = Array.isArray(targets) ? targets : [targets];
  for (const t of list) {
    if (t === 'all') {
      result.isAtAll = true;
      result.atText = '@所有人 ';
    } else if (USER_PHONES[t]) {
      result.atMobiles.push(USER_PHONES[t]);
      result.atText += `@${USER_PHONES[t]} `;
    }
  }
  return result;
}

/**
 * 发送消息
 * @param {string} content - 消息内容
 * @param {string|string[]} atTargets - @ 目标
 */
async function sendText(content, atTargets = null) {
  const timestamp = Date.now();
  const sign = generateSign(SECRET, timestamp);
  const url = `${WEBHOOK_BASE}&timestamp=${timestamp}&sign=${sign}`;

  const { atMobiles, isAtAll, atText } = parseAtTargets(atTargets);

  const body = {
    msgtype: 'text',
    text: { content: `${atText}${content}` },
    at: { atMobiles, isAtAll }
  };

  const res = await axios.post(url, body);
  return res.data;
}

// 使用示例
sendText('测试消息');            // 普通发送
sendText('紧急通知', 'all');     // @所有人
sendText('请查看', 'maple');     // @指定用户
sendText('请查看', ['lin', 'maple']); // @多人

import requests
import json
import time
import hmac
import hashlib
import base64
import urllib.parse

# 配置
WEBHOOK_BASE = "你的 Webhook 地址"
SECRET = "你的加签密钥"

# 用户手机号映射
USER_PHONES = {
    "lin": "手机号",
    "琳琳": "手机号",
    "maple": "手机号",
    "鸿枫": "手机号"
}

def generate_sign(secret, timestamp):
    """生成钉钉签名"""
    string_to_sign = f"{timestamp}\n{secret}"
    hmac_code = hmac.new(
        secret.encode('utf-8'),
        string_to_sign.encode('utf-8'),
        digestmod=hashlib.sha256
    ).digest()
    sign = urllib.parse.quote_plus(base64.b64encode(hmac_code))
    return sign

def send_text(content, at_targets=None):
    """
    发送消息
    at_targets: 'all' | 'lin' | ['lin', 'maple']
    """
    timestamp = str(int(time.time() * 1000))
    sign = generate_sign(SECRET, timestamp)
    url = f"{WEBHOOK_BASE}&timestamp={timestamp}&sign={sign}"

    # 解析 @ 目标
    at_mobiles = []
    is_at_all = False
    at_text = ""

    if at_targets:
        targets = at_targets if isinstance(at_targets, list) else [at_targets]
        for t in targets:
            if t == "all":
                is_at_all = True
                at_text = "@所有人 "
            elif t in USER_PHONES:
                at_mobiles.append(USER_PHONES[t])
                at_text += f"@{USER_PHONES[t]} "

    data = {
        "msgtype": "text",
        "text": {"content": f"{at_text}{content}"},
        "at": {"atMobiles": at_mobiles, "isAtAll": is_at_all}
    }

    response = requests.post(url, json=data)
    return response.json()

# 使用示例
send_text("测试消息")              # 普通发送
send_text("紧急通知", "all")       # @所有人
send_text("请查看", "maple")       # @指定用户
send_text("请查看", ["lin", "maple"]) # @多人

{
  "msgtype": "markdown",
  "markdown": {
    "title": "任务提醒",
    "text": "### 任务提醒\n\n@手机号 请在下班前完成以下任务:\n\n- [ ] 代码审查\n- [ ] 更新文档"
  },
  "at": {
    "atMobiles": ["手机号"]
  }
}

钉钉 Webhook 消息推送完全指南

钉钉 Webhook 完全指南

一、基础知识

Webhook vs 插件

消息格式支持

二、@ 用户功能

核心原理

JSON 示例

三、完整 Shell 脚本

四、Node.js 实现

五、Python 实现

六、避坑指南

1. 自定义关键词

2. 手机号必须准确

3. @ 的两个条件缺一不可

4. 避免滥用 @所有人

5. 发送频率限制

七、Markdown 格式 @ 用户

更多推荐文章

相关免费在线工具

钉钉 Webhook 消息推送完全指南

钉钉 Webhook 完全指南

一、基础知识

Webhook vs 插件

消息格式支持

二、@ 用户功能

核心原理

JSON 示例

三、完整 Shell 脚本

四、Node.js 实现

五、Python 实现

六、避坑指南

1. 自定义关键词

2. 手机号必须准确

3. @ 的两个条件缺一不可

4. 避免滥用 @所有人

5. 发送频率限制

七、Markdown 格式 @ 用户

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具