Mercado Pago webhooks
Last verified against Mercado Pago's documentation on September 27, 2026.
Mercado Pago sends webhook notifications when a payment, an order, a subscription, or a chargeback changes. Its signature is built from pieces spread across the request: the data.id query parameter, the x-request-id header, and a timestamp from the x-signature header. Miss one of those, or skip lowercasing the ID, and validation fails. Mercado Pago keeps retrying until it gets a 200 or 201. This page covers what Mercado Pago sends, how it delivers, how to fix the common errors, and where HookDeploy fits.
What Mercado Pago sends webhooks for
| Topic | Typical use |
|---|---|
payment | Track payment status |
order | Track orders |
subscription_preapproval, subscription_authorized_payment | Keep subscriptions in sync |
topic_chargebacks_wh | Respond to chargebacks |
Each notification is a JSON POST with an action, a type, and the affected resource’s ID under data.id, which is also sent as the data.id query parameter. Fetch the resource from the API for its details.
How Mercado Pago delivers webhooks
| Behavior | Detail |
|---|---|
| Method and format | POST with a JSON body and data.id in the query string |
| Signature header | x-signature, formatted ts=<timestamp>,v1=<hex> |
| Signed manifest | id:{data.id};request-id:{x-request-id};ts:{ts};, with any missing part left out |
| Signing scheme | Hex HMAC-SHA256 of the manifest, keyed with your application’s webhook secret |
| Success | 200 or 201 within 22 seconds |
| Retries | Every 15 minutes at first, then at longer intervals, until the notification is confirmed |
| Unverifiable topics | QR code notifications can’t be validated with the secret signature |
Common Mercado Pago webhook errors and how to fix them
Signature never matches
- Uppercase ID. For alphanumeric IDs, lowercase
data.idbefore building the manifest. - Wrong source for the ID. Use the
data.idquery parameter. - Missing pieces. If a value isn’t in the notification, leave that pair out of the manifest entirely.
- Wrong secret. Use the secret from Your integrations, then Webhooks, for the same application and mode.
Notification details are missing
Notifications carry only the resource ID. Fetch the payment or order from the API.
Retries never stop
Mercado Pago keeps retrying until it gets a 200 or 201. Return one of those as soon as you’ve accepted the notification.
Duplicate notifications
Retries resend the same notification. Deduplicate on the resource ID together with the action.
Why use HookDeploy with Mercado Pago
Capture every notification
HookDeploy captures every Mercado Pago webhook at Cloudflare’s edge and responds right away, before forwarding it to your server. Mercado Pago gets its 200 right away, so retries stop, and the notification waits in HookDeploy until your server can process it.
- Destination retries. Starter retries 3 times (after 30 seconds, 5 minutes, and 30 minutes). Pro and Scale retry up to 5 times on a schedule you choose. Free doesn’t retry automatically.
- Incidents. Forward failures are grouped into incidents, and you can bulk-replay them once your server recovers.
- History. HookDeploy keeps captured webhooks for your plan’s retention period, from 7 days on Free to 365 days on Enterprise.
One webhook, many systems
Send each Mercado Pago event to your app, your accounting or ERP system, and an alert channel in parallel. A failing destination doesn’t hold up the others. Free includes 1 destination per endpoint, Starter includes 5, and Pro and above are unlimited.
Deliver to systems Mercado Pago can’t reach
The HookDeploy Agent connects outward from your network over mTLS and delivers events to a local port, so a billing or fulfillment service in a private network can receive Mercado Pago events with no public endpoint.
Develop against real events
A tap sends a temporary copy of live Mercado Pago events to 127.0.0.1 on your machine while production keeps receiving them.
Know the limits
- Headers and query string. HookDeploy forwards the
x-signatureandx-request-idheaders and thedata.idquery parameter unchanged, removing only HookDeploy’s owntokenparameter. - Plan limits. On Free, requests beyond the monthly allowance or the daily limit get a
429, which Mercado Pago treats as a failed delivery. Paid plans keep accepting traffic past the included volume.
Retries, replays, and duplicates
Mercado Pago’s signature covers the ID, the request ID, and the timestamp, not the body, and HookDeploy forwards all three unchanged. Retries and replays validate like the original delivery, unless your handler rejects old timestamps. If it does, skip that check for requests carrying an auth header you inject on the destination.
Mercado Pago’s retries, HookDeploy’s retries, and replays can all deliver the same notification. Deduplicate on the resource ID and action.
Set up Mercado Pago with HookDeploy
- In HookDeploy, create an endpoint (for example,
Mercado Pago production) and copy its URL. - On the Forwarding tab, add a destination pointing to your handler, or to an agent for private delivery, and set its retries.
- In Mercado Pago, open Your integrations, select your application, then Webhooks, and configure a notification URL with your HookDeploy URL and the topics you want. Reveal and copy the secret.
- Use the simulator to send a test notification, and confirm it appears in HookDeploy and reaches your handler.
Example handler (Node.js and Express)
import crypto from 'node:crypto';
import express from 'express';
const app = express();
app.post('/webhooks/mercadopago', express.json(), async (req, res) => {
const parts = Object.fromEntries(
(req.get('x-signature') ?? '').split(',').map((p) => p.trim().split('=')));
const dataId = String(req.query['data.id'] ?? '').toLowerCase();
const requestId = req.get('x-request-id');
let manifest = '';
if (dataId) manifest += `id:${dataId};`;
if (requestId) manifest += `request-id:${requestId};`;
if (parts.ts) manifest += `ts:${parts.ts};`;
const expected = crypto
.createHmac('sha256', process.env.MP_WEBHOOK_SECRET)
.update(manifest)
.digest('hex');
const received = parts.v1 ?? '';
const valid =
received.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
if (!valid) return res.status(401).send('Invalid signature');
res.sendStatus(200);
await enqueue({ type: req.body.type, action: req.body.action, resourceId: req.body.data?.id });
// Deduplicate on resourceId plus action, then fetch the resource from the API.
});
FAQ
How do I validate a Mercado Pago webhook?
Build the manifest id:{data.id};request-id:{x-request-id};ts:{ts}; from the data.id query parameter, the x-request-id header, and the ts value in x-signature. Compute a hex HMAC-SHA256 of it with your webhook secret and compare it to the v1 value in x-signature.
Why does Mercado Pago signature validation fail?
The most common causes are not lowercasing an alphanumeric data.id, taking the ID from the wrong place, or including a pair in the manifest that wasn't in the notification. Mercado Pago's SDKs include a validator that handles this.
How does Mercado Pago retry notifications?
If it doesn't get a 200 or 201 within 22 seconds, it retries every 15 minutes, then at longer intervals, until the notification is confirmed.
Why doesn't the notification include payment details?
It carries only the resource ID. Fetch the payment or order from the API to get its current details.
Can every Mercado Pago notification be validated?
No. QR code notifications can't be validated with the secret signature. Contact Mercado Pago support if you need to verify their origin.
Does HookDeploy break Mercado Pago signature validation?
No. The signature covers the data.id query parameter, the x-request-id header, and a timestamp, and HookDeploy forwards all of them unchanged, so first deliveries, retries, and replays all validate.