mp-webhooks

mp-webhooks

此技能适用于所有通知。HMAC 验证模式只在这里定义，其他所有技能都会引用此处。

---

步骤 0 — 仅在执行由 MCP 支持的操作前连接

此技能启动时，不要检查 MCP 状态。搭建脚手架和审查接收器模式都是静态操作，无需连接 MCP。

仅在即将执行以下选定操作时连接：

操作	所需 MCP 工具
获取特定语言的签名示例	search_documentation
查询未知主题或特定国家/地区的主题	search_documentation
注册或轮换回调 URL	save_webhook
确认或诊断 Webhook 投递情况	notifications_history

按需认证流程：

1. 如果可以调用，直接尝试预定工具。不要调用 application_list 来探测连接。
2. 如果该工具不可用或返回认证错误，请调用 mcp__plugin_mercadopago_mcp__authenticate。
3. 使用开发者所用的语言显示可点击的 OAuth 链接，并告知他们使用 Cmd+Click（Mac）或 Ctrl+Click（Windows/Linux）打开，不要将 URL 复制到外部浏览器。
4. 开发者返回后，直接重试预定工具。绝不要要求他们粘贴回调 URL。
5. 如果未加载 MCP 工具，请说明如何启用 plugin:mercadopago:mcp。静态搭建脚手架/审查工作仍应可离线完成。

仅当开发者选择由 MCP 支持的操作时，才显示此先决条件检查清单：

Before configuring webhooks live, you'll need:
- [ ] A Mercado Pago developer account
- [ ] An app created in the Developer Dashboard
- [ ] Test credentials: APP_USR- access token + public key (tab {test_tab})
- [ ] The webhook signature secret (Dashboard → Webhooks → Signature secret)
Connection will be requested immediately before the selected MCP operation.

---

步骤 1 — 确定操作

询问开发者（或根据 $ARGUMENTS 推断）他们想执行以下哪项操作：

操作	要调用的工具	适用情形
在 MP 应用上配置 Webhook URL	save_webhook	首次设置或轮换端点
诊断投递故障	notifications_history	调查遗漏/失败的通知
搭建接收器代码脚手架	（不调用 MCP — 渲染下方模式）	将接收器添加到代码库

可以串联执行：搭建接收器脚手架 → save_webhook → 触发一笔真实测试付款 → 使用 notifications_history 确认投递情况。

---

步骤 2 — 接收器模式（HMAC-SHA256）

Mercado Pago 使用控制面板中 Webhooks → Signature secret 下返回的密钥为每条通知签名。x-signature 标头由 ts=...,v1=... 组成，其中 v1 是规范字符串 "id:{data.id};request-id:{x-request-id};ts:{ts};" 的 HMAC-SHA256。

每个接收器都必须：

1. 从请求标头中读取 x-signature 和 x-request-id。
2. 从 x-signature 中解析出 ts 和 v1。
3. 使用 data.id（来自 JSON 请求体）、x-request-id 和 ts 构造规范字符串。
4. 计算 HMAC-SHA256(canonical, secret)，并以恒定时间方式与 v1 比较。
5. 如果签名有效，立即响应 200，之后再异步处理事件。对于非 200 响应，Mercado Pago 会以指数退避方式重试，最长约 24 小时。
6. 确保幂等：同一通知 ID 可能会重复到达。使用 data.id + 主题作为去重键。

规范字符串

id:<data.id>;request-id:<x-request-id>;ts:<ts>;

参考代码片段（Node.js、Express）

import crypto from "node:crypto";

const SECRET = process.env.MP_WEBHOOK_SECRET;

export function mpWebhook(req, res) {
  const signature = req.header("x-signature") ?? "";
  const requestId = req.header("x-request-id") ?? "";
  const parts = Object.fromEntries(
    signature.split(",").map((p) => p.split("=").map((s) => s.trim()))
  );
  const ts = parts.ts;
  const v1 = parts.v1;
  const dataId = req.body?.data?.id;
  if (!ts || !v1 || !dataId || !requestId) return res.status(400).end();

  const canonical = `id:${dataId};request-id:${requestId};ts:${ts};`;
  const expected = crypto.createHmac("sha256", SECRET).update(canonical).digest("hex");

  const ok = expected.length === v1.length &&
             crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
  if (!ok) return res.status(401).end();

  res.status(200).end();
  // process asynchronously after responding 200
  queueMicrotask(() => handleEvent(req.body));
}

对于其他语言，请在查询 MCP search_documentation 之前立即执行步骤 0，并使用：

• "webhook signature validation {language}"（例如：python、java、php、ruby、go、dotnet）。

---

第 3 步 — 主题

通知正文包含 type（主题）和 data.id。常见主题：

主题	触发时机	要获取的资源
payment	付款状态变更（Payments API）	GET /v1/payments/{id}
orders	Point / QR Code 事件（Orders API）	GET /v1/orders/{id}
merchant_order	商家订单已更新——旧版（Checkout Pro / 通过旧版 API 处理的 QR）	GET /merchant_orders/{id}
topic_claims_integration_wh	拒付	GET /v1/chargebacks/{id}
point_integration_wh	Point 设备事件——旧版（旧版 Point Integration API）	Point 旧版 API——按国家查询 MCP
subscription_preapproval	订阅状态变更	GET /preapproval/{id}
subscription_authorized_payment	定期扣款尝试	GET /authorized_payments/{id}

如果主题不在此表中，请立即执行第 0 步，然后查询 MCP 获取最新列表，不要猜测。

---

第 4 步 — 在 Mercado Pago 上配置（save_webhook）

按需连接： 在调用 save_webhook 前立即执行第 0 步。不要先调用 application_list。

mcp__plugin_mercadopago_mcp__save_webhook(
  callback="https://<production-url>/mp/webhook",
  callback_url="https://<your-domain>/mp/webhook",
  topics=["payment", "merchant_order", ...]
)

确认响应显示的 URL 和主题均已正确注册。

---

第 5 步 — 冒烟测试（真实测试付款）

MCP 中已不再提供 simulate_webhook。要测试接收端：

1. 使用测试凭证 + 测试用户 + 测试卡进行真实付款
2. 付款状态变更时会自动触发 webhook
3. 确认接收端返回了 200，并以幂等方式处理事件

在使用 notifications_history 确认投递情况前，请立即执行第 0 步：

mcp__plugin_mercadopago_mcp__notifications_history()

---

第 6 步 — 诊断投递失败

按需连接： 在调用 notifications_history 前立即执行第 0 步。不要先调用 application_list。

mcp__plugin_mercadopago_mcp__notifications_history()

返回投递指标和失败原因明细（超时、非 200 响应、签名不匹配）。生产环境中缺少通知时可使用此功能。

---

注意事项

• 在处理之前先响应 200。耗时较长的同步处理程序会导致重试，淹没接收端，并掩盖真正的故障。
• Mercado Pago 遇到非 200 响应时会采用指数退避重试，最长约 24h——暂时性错误可能导致重复通知泛滥。
• 让处理程序具备幂等性。使用 data.id + type 作为去重键。
• 不要只相信 JSON 正文——务必先验证签名。
• IPN（旧版 ?id=&topic= GET 样式通知）已弃用。新集成只使用此处描述的现代签名 webhook。

---

此技能不做什么

• 不会搭建外围集成。请使用 mp-integrate。
• 不会评估质量。请使用 mp-review。
• 不会凭记忆编造主题名称——不确定时请查询 MCP。