From mercadopago
Configures and validates Mercado Pago webhooks. Wraps save_webhook/notifications_history tools and provides HMAC-SHA256 signature validation pattern for receiver implementation.
How this skill is triggered — by the user, by Claude, or both
Slash command
/mercadopago:mp-webhooksThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill is for everything notifications. It is the only place where the HMAC validation pattern lives — every other skill defers here.
This skill is for everything notifications. It is the only place where the HMAC validation pattern lives — every other skill defers here.
ListMcpResourcesTool is unreliable for this MCP (always returns "No resources found"). The bootstrap tools authenticate / complete_authentication are always present and prove nothing.
Check whether mcp__plugin_mercadopago_mcp__application_list is callable AND returns a real payload. If not, stop and tell the user:
Call
mcp__plugin_mercadopago_mcp__authenticate, show the URL as a clickable link, and say: "When you see Authentication Successful in the browser, come back and say anything." When the user responds, callapplication_listdirectly — do NOT callcomplete_authenticationfirst (it hangs when the callback was already consumed). Never ask the user to paste the callback URL — it contains a sensitive OAuth code.
Ask the developer (or infer from $ARGUMENTS) which of these they want:
| Action | Tool to call | When |
|---|---|---|
| Configure the webhook URL on the MP application | save_webhook | First time setup or rotating the endpoint |
| Diagnose delivery failures | notifications_history | Investigating missed/failed notifications |
| Scaffold the receiver code | (no MCP call — render the pattern below) | Adding the receiver to the codebase |
You may chain them: scaffold the receiver → save_webhook → trigger a real test payment to verify end to end → use notifications_history to confirm delivery.
Mercado Pago signs every notification with the secret returned in the dashboard at Webhooks → Signature secret. The x-signature header is composed of ts=...,v1=... where v1 is the HMAC-SHA256 of the canonical string "id:{data.id};request-id:{x-request-id};ts:{ts};".
Every receiver MUST:
x-signature and x-request-id from the request headers.ts and v1 out of x-signature.data.id (from the JSON body) and x-request-id and ts.HMAC-SHA256(canonical, secret) and compare in constant time with v1.200 immediately if the signature is valid — process the event asynchronously afterwards. Mercado Pago retries on non-200 responses with exponential backoff for up to ~24 hours.data.id + topic as the dedup key.id:<data.id>;request-id:<x-request-id>;ts:<ts>;
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));
}
For other languages, query MCP search_documentation with:
"webhook signature validation {language}" (e.g., python, java, php, ruby, go, dotnet).The notification body contains type (the topic) and data.id. Common topics:
| Topic | When | Resource to fetch |
|---|---|---|
payment | Payment status change (Payments API) | GET /v1/payments/{id} |
orders | Point / QR Code event (Orders API) | GET /v1/orders/{id} |
merchant_order | Merchant order updated — legacy (Checkout Pro / QR attended via legacy API) | GET /merchant_orders/{id} |
topic_claims_integration_wh | Chargebacks | GET /v1/chargebacks/{id} |
point_integration_wh | Point device events — legacy (old Point Integration API) | Point legacy API — query MCP for the country |
subscription_preapproval | Subscription status change | GET /preapproval/{id} |
subscription_authorized_payment | Recurring charge attempt | GET /authorized_payments/{id} |
If a topic is not in this table, query MCP for the latest list rather than guessing.
save_webhook)mcp__plugin_mercadopago_mcp__save_webhook(
callback="https://<production-url>/mp/webhook",
callback_sandbox="https://<staging-url>/mp/webhook",
topics=["payment", "merchant_order", ...]
)
Confirm the response shows the URL and topics correctly registered.
simulate_webhook no longer exists in the MCP. To test your receiver:
200 and processed the eventTo confirm delivery, use notifications_history:
mcp__plugin_mercadopago_mcp__notifications_history(
application_id="<your_app_id>"
)
This shows which notifications were delivered, failed, or retried.
mcp__plugin_mercadopago_mcp__notifications_history()
Returns delivery metrics and a breakdown of failures (timeouts, non-200 responses, signature mismatches). Use this when notifications are missing in production.
200 before processing. A long synchronous handler causes retries that flood the receiver and can mask the real failure.data.id + type as the dedup key.?id=&topic= GET-style notification) is deprecated. New integrations use only the modern signed webhook described here.mp-integrate.mp-review.npx claudepluginhub anthropics/claude-plugins-official --plugin mercadopagoScaffolds a complete Mercado Pago payment integration by collecting country, product, and SDK details, querying the official MCP server for live docs, and producing a ready-to-paste code bundle.
Webhook validation patterns with signature verification, event logging, and testing tools. Use when implementing webhooks, validating webhook signatures, securing payment webhooks, testing webhook endpoints, preventing replay attacks, or when user mentions webhook security, Stripe webhooks, signature verification, webhook testing, or event validation.
Designs reliable webhook systems using Stripe patterns: resource.action event naming, JSON envelope payloads, HMAC-SHA256 signing, exponential backoff retries, deduplication, and endpoint implementation.