Webhooks notifications, also known as web callbacks, are an effective method that allows Mercado Pago servers to send information in real time when a specific event related to your integration occurs. Instead of your system constantly querying for updates, Webhooks allow the passive and automatic transmission of data between Mercado Pago and your integration through an HTTPS POST request, optimizing communication and reducing server load.

Below, we present a step-by-step guide to receiving payment notifications in integrations with QR Code. Once configured, Webhook notifications will be sent whenever a relevant event occurs, such as approved payment (processing), refund, failure, cancellation or expiration.

1. Go to Your integrations and select the application integrated with QR Code for which you want to activate notifications.

2. In the left menu, select Webhooks > Configure notifications.

3. Select the Production mode tab and provide an HTTPS URL to receive notifications with your productive integration.

4. Select the Order (Mercado Pago) event to receive notifications, which will be sent in JSON format via an HTTPS POST to the URL specified above.

5. Finally, click on Save configuration. An exclusive secret key will be generated for the application, which will allow you to validate the authenticity of the received notifications, ensuring that they were sent by Mercado Pago. Keep in mind that this key does not have an expiration date and its periodic renewal is not mandatory, although it is recommended. To do this, simply click the Reset button.

Once completed, your Webhooks notifications for QR Code will be configured and you will be able to receive the following alerts about the order:

• Processed (order.processed)
• Canceled (order.canceled)
• Refunded (order.refunded)
• Expired (order.expired)

To ensure that notifications are configured correctly, it is necessary to simulate their reception. To do this, follow the steps below.

1. After configuring your Webhooks, click Simulate notification.
2. On the simulation screen, select the URL to be tested.
3. Next, choose the event type and enter the ID that will be sent in the notification body (Data ID).

4. Finally, click on Send test to verify the request, the response provided by the server, and the event description. You will receive a response as shown in the examples below, representing the body of the notification received on your server.

json
Copiar
{
  "action": "order.processed",
  "api_version": "v1",
  "application_id": "7364289770550796",
  "data": {
    "external_reference": "ER_123456",
    "id": "ORD01JV3AW3NFSTSTB669F41NACDX",
    "status": "processed",
    "status_detail": "accredited",
    "total_amount": "30.00",
    "total_paid_amount": "30.00",
    "transactions": {
      "payments": [
        {
          "amount": "30.00",
          "id": "PAY01JV3AW3NFSTSTB669F4JSAA6C",
          "paid_amount": "30.00",
          "payment_method": {
            "id": "account_money",
            "installments": 1,
            "type": "account_money"
          },
          "reference": {
            "id": "92937960454"
          },
          "status": "processed",
          "status_detail": "accredited"
        }
      ]
    },
    "type": "qr",
    "version": 2
  },
  "date_created": "2025-05-12T22:46:59.635090485Z",
  "live_mode": false,
  "type": "order",
  "user_id": "1403498245"
}

Validating the origin of a notification is essential to ensure the security and authenticity of the received information. This process helps prevent fraud and ensures that only legitimate notifications are processed.

Mercado Pago will send to your server a notification similar to the example below for an order topic alert. This example includes the complete notification, which contains the query params, the body, and the header of the notification.

• Query params: These are query parameters that accompany the URL. In the example, we have data.id=ORD01JQ4S4KY8HWQ6NA5PXB65B3D3 and type=order.
• Body: The body of the notification contains detailed information about the event, such as action, api_version, application_id, date_created, id, live_mode, type, user_id, and data.
• Header: The header contains important metadata, including the secret signature of the notification x-signature.

plain
Copiar
POST /test?data.id=ORD01JQ4S4KY8HWQ6NA5PXB65B3D3&type=order HTTP/1.1
Host: prueba.requestcatcher.com
Accept: */*
Accept-Encoding: *
Connection: keep-alive
Content-Length: 177
Content-Type: application/json
Newrelic: eyJ2IjpbMCwxXSwiZCI6eyJ0eSI6IkFwcCIsImFjIjoiOTg5NTg2IiwiYXAiOiI5NjA2MzYwOTQiLCJ0eCI6ImY4MzljZjg4ODg2MGRmZTIiLCJ0ciI6ImMwOGMwZGMyMjNjZDY2YjJkZWQwMjUxZmYxNWNiNGQ1IiwicHIiOjEuMjUwMzIsInNhIjp0cnVlLCJ0aSI6MTc0Mjg0MjU4MDE2NCwiaWQiOiIxOGI2NDcxNjNkNzI3NjU4IiwidGsiOiIxNzA5NzA3In19=
Traceparent: 00-c08c0dc223cd66b2ded0251ff15cb4d5-18b647163d727658-01
Tracestate: 1709707@nr=0-0-989586-960636094-18b647163d727658-f839cf888860dfe2-1-1.250320-1742842580164
User-Agent: restclient-node/4.15.3
X-Request-Id: 2066ca19-c6f1-498a-be75-1923005edd06
X-Rest-Pool-Name: /services/webhooks.js
X-Retry: 0
X-Signature: ts=1742505638683,v1=ced36ab6d33566bb1e16c125819b8d840d6b8ef136b0b9127c76064466f5229b
X-Socket-Timeout: 22000
{"action":"order.action_required","api_version":"v1","application_id":"76506430185983","date_created":"2021-11-01T02:02:02Z","id":"123456","live_mode":false,"type":"order","user_id":2025701502,"data":{"id":"ORD01JQ4S4KY8HWQ6NA5PXB65B3D3"}}

From the received Webhook notification, you can validate the authenticity of its origin through the secret key. This key will be sent in the x-signature header, which will be similar to the example below.

plain
Copiar
ts=1742505638683,v1=ced36ab6d33566bb1e16c125819b8d840d6b8ef136b0b9127c76064466f5229b

To confirm the validation, it is necessary to extract the key from the header and compare it with the key provided for your application in Your integrations.

Follow one of the approaches below to validate the authenticity of the notification.

<?php
use MercadoPago\Webhook\WebhookSignatureValidator;
use MercadoPago\Exceptions\InvalidWebhookSignatureException;

try {
    WebhookSignatureValidator::validate(
        $_SERVER['HTTP_X_SIGNATURE'],
        $_SERVER['HTTP_X_REQUEST_ID'],
        $_GET['data_id'],
        $secret
    );
    http_response_code(200);
} catch (InvalidWebhookSignatureException $e) {
    http_response_code(401);
}

import { WebhookSignatureValidator, InvalidWebhookSignatureError } from 'mercadopago';

try {
    WebhookSignatureValidator.validate({
        xSignature: req.headers['x-signature'],
        xRequestId: req.headers['x-request-id'],
        dataId:     req.query['data.id'],
        secret,
    });
    res.sendStatus(200);
} catch (err) {
    if (err instanceof InvalidWebhookSignatureError) res.status(401).end();
    else throw err;
}

from mercadopago.webhook import WebhookSignatureValidator, InvalidWebhookSignatureError

try:
    WebhookSignatureValidator.validate(
        request.headers.get(“x-signature”),
        request.headers.get(“x-request-id”),
        request.args.get(“data.id”),
        secret,
    )
    return “”, 200
except InvalidWebhookSignatureError:
    return “”, 401

import “github.com/mercadopago/sdk-go/pkg/webhook”

err := webhook.ValidateSignature(
    r.Header.Get(“x-signature”),
    r.Header.Get(“x-request-id”),
    r.URL.Query().Get(“data.id”),
    secret,
)
if err != nil {
    w.WriteHeader(http.StatusUnauthorized)
    return
}
w.WriteHeader(http.StatusOK)

using MercadoPago.Error;
using MercadoPago.Webhook;

try {
    WebhookSignatureValidator.Validate(
        xSignature: Request.Headers[“x-signature”],
        xRequestId: Request.Headers[“x-request-id”],
        dataId:     Request.Query[“data.id”],
        secret:     secret);
    return Ok();
} catch (InvalidWebhookSignatureException) {
    return Unauthorized();
}

import com.mercadopago.webhook.WebhookSignatureValidator;
import com.mercadopago.exceptions.MPInvalidWebhookSignatureException;

try {
    WebhookSignatureValidator.validate(
        request.getHeader(“x-signature”),
        request.getHeader(“x-request-id”),
        request.getParameter(“data.id”),
        secret);
    response.setStatus(200);
} catch (MPInvalidWebhookSignatureException e) {
    response.setStatus(401);
}

require 'mercadopago/webhook/validator'

begin
    Mercadopago::Webhook::Validator.validate(
        request.headers['x-signature'],
        request.headers['x-request-id'],
        request.params['data.id'],
        secret
    )
    head :ok
rescue Mercadopago::Webhook::InvalidWebhookSignatureError
    head :unauthorized
end

When you receive a notification on your platform, Mercado Pago expects a response to validate that the reception was correct. To do this, you must return an HTTP STATUS 200 (OK) or 201 (CREATED).

The waiting time for this confirmation will be 22 seconds. If this confirmation is not sent, the system will understand that the notification was not received and will make a new attempt to send it every 15 minutes until it receives the response. After the third attempt, the deadline will be extended, but the deliveries will continue to happen.

After responding to the Webhook notification and confirming its receipt, only if the information received is not sufficient and you need additional information, you can obtain all the data about the notified resource by sending a GET to the endpoint /v1/orders/{id}API.

With this information, you will be able to make the necessary updates to your platform, such as updating an approved payment.