SuperAPI AI 工具集

mp-webhooks

编程与开发

查看项目

更新于 11-11 20:22

技能介绍

mp-webhooks 是 Mercado Pago 插件市场提供的技能,聚焦于通知(Webhook)相关的一切事务,也是 HMAC 校验模式的唯一所在,其他技能遇到签名校验都会指向这里。

用途 该技能用于配置和校验 Mercado Pago Webhook,主要围绕三个动作:在 Mercado Pago 应用上配置或轮换回调 URL、诊断通知投递失败、为代码库搭建接收端(receiver)代码骨架。这些动作可以串联:先搭建接收端,再注册 Webhook,触发一笔真实测试支付,最后确认投递情况。

主要能力

  1. MCP 工具封装:封装了 save_webhook(注册或轮换回调 URL)与 notifications_history(确认或诊断 Webhook 投递),并可借助 search_documentation 获取特定语言的签名示例或解析未知、特定国家/地区的主题。
  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。接收端必须读取 x-signature 与 x-request-id,解析 ts 和 v1,构建规范字符串,计算 HMAC-SHA256 并以常量时间与 v1 比较。
  3. 接收端模式:签名有效时立即返回 200,然后再异步处理事件;非 200 响应会触发指数退避重试,最长约 24 小时。处理需幂等,同一通知 id 可能多次到达,建议用 data.id + topic 作为去重键。资料提供了 Node.js Express 参考代码片段,其他语言可通过 MCP 查询对应签名示例。
  4. 主题说明:通知体包含 type(主题)与 data.id,常见主题包括 payment、orders、merchant_order、topic_claims_integration_wh、point_integration_wh、subscription_preapproval、subscription_authorized_payment,各主题对应不同的资源查询接口,如 GET /v1/payments/{id}、GET /v1/orders/{id} 等。
  5. 配置与测试:通过 save_webhook(callback, callback_url, topics) 注册回调并确认响应中的 URL 与主题;simulate_webhook 已从 MCP 移除,测试方式是使用测试凭证、测试用户和测试卡发起真实支付,支付状态变化后 Webhook 自动触发,再用 notifications_history 确认投递。
  6. 失败诊断:notifications_history 返回投递指标及失败细分(超时、非 200 响应、签名不匹配),用于排查生产环境通知缺失。

使用方式 静态的接收端搭建与评审无需 MCP 连接,可离线完成。仅在选择 MCP 支持的操作用前才需连接:直接尝试目标工具,若不可用或返回鉴权错误再调用 authenticate,在开发者所用语言中展示可点击的 OAuth 链接并提示 Cmd+Click 或 Ctrl+Click,不要将 URL 复制到外部浏览器;返回后直接重试目标工具,不要要求粘贴回调 URL。若 MCP 工具未加载,需说明如何启用 plugin:mercadopago:mcp。配置实际 Webhook 前需要:Mercado Pago 开发者账号、在开发者面板创建的应用、测试凭证(APP_USR- 访问令牌 + 公钥)以及签名密钥。

适用场景 适用于接入 Mercado Pago 的支付状态变更、Point/QR 订单事件、商户订单更新、拒付、订阅状态变化、周期性扣款尝试等通知的开发场景,尤其适合需要实现安全签名校验、幂等处理与投递故障排查的集成工作。

限制 该技能不搭建周边集成(应使用 mp-integrate),不评估质量(应使用 mp-review),也不会凭记忆编造主题名称,不确定时应查询 MCP。旧版 IPN(?id=&topic= 的 GET 式通知)已废弃,新集成只使用本文所述的现代签名 Webhook。资料未提供具体收费、价格等信息。