In addition to the primary orders topic, Mercado Pago provides optional topics to notify your application about integration management events, such as account linking via OAuth, buyer-initiated claims, chargebacks, and fraud alerts. These notifications complement the main flow and ensure that your system remains up to date with events that go beyond payment processing.

None of these topics replace the orders topic or are mandatory. Enable only those relevant to your integration.

Follow the steps below to enable the optional topics in your integration.

1. Go to Your integrations and select the application for which you want to enable notifications.

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

3. Select the Production mode tab and provide an HTTPS URL to receive notifications.

4. In the optional topics section, select the events you want to enable: Application linking, Claims, Chargebacks, and/or Fraud alerts.

5. Finally, click Save configuration. This will generate a secret keyKey used to validate the authenticity of each notification received. for your application. Note that this key has no expiration date and periodic renewal is not mandatory, though it is recommended. To do so, simply click the Reset button.

To ensure that notifications are configured correctly, simulate receiving them by following the step-by-step instructions below.

1. After configuring the URL and events, click Save configuration.

2. Then click Simulate to verify that the indicated URL is receiving notifications correctly.

3. On the simulation screen, select the URL to be tested.

4. Choose the type of event you want to test and enter the Resource ID that will be sent in the notification body (Data ID).

5. Finally, click Send test to check the request, the server response, and the event description.

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

Mercado Pago will send your server a notification that includes the following components:

• Query params: Accompany the request URL. They contain data.id with the notified resource identifier and type with the topic name.
• Body: Contains the details of the notified event, such as action, api_version, application_id, date_created, id, live_mode, type, user_id and data.
• Header: Includes the secret signature x-signature, which allows validating the authenticity of the notification.

Below are examples of notifications for each topic.

plain
Copiar
POST /?data.id=123456789&type=mp-connect HTTP/1.1
Host: test-optional-nots.requestcatcher.com
Accept: */*
Accept-Encoding: *
Connection: keep-alive
Content-Length: 187
Content-Type: application/json
User-Agent: restclient-node/5.1.10
X-Request-Id: 4ed4fa2b-0b31-42ec-a62f-ad793c486c59
X-Rest-Pool-Name: /services/webhooks.js
X-Retry: 0
X-Signature: ts=1781009491,v1=654866c48793d9f716f255f8a8e6cb162f643d93b29391daa6ac7ce78cf0ce81
X-Socket-Timeout: 22000
{"action":"application.authorized","api_version":"v1","data":{"id":"123456789"},"date_created":"2026-06-12T13:14:01.351Z","id":100000000000,"live_mode":true,"type":"mp-connect","user_id":123456789}

From the received notification, you can validate the authenticity of its origin using the secret key. This key will be sent in the x-signature header, with the following format:

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 receipt was correct. To do this, return an HTTP STATUS 200 or 201 within 22 seconds of receiving it.

We recommend that you first respond with a 200 or 201, and then process the notification on the server, to avoid duplicate notifications.

If this response is not sent, the system will make new delivery attempts every 15 minutes. After the first failures, the interval progressively increases, but deliveries continue until the notification is confirmed.

Additionally, keep in mind:

• Upon receiving a fraud alert, you must refund the payment without delivering the order by making a call to the Refunds API.
• For chargeback management, see the documentation.