Additionally, beyond the primary orders topic, Mercado Pago offers optional topics that notify your application about integration management events: account linking via OAuth, buyer-initiated claims, chargebacks, and fraud alerts. These notifications complement the main flow and allow you to keep your system in sync with events that go beyond payment processing.

None of these topics replace the orders topic nor are they mandatory. Activate only the ones relevant to your integration.

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

1. Access Your integrations and select the application 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.

4. In the optional topics section, select the events you want to activate: 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 required, although 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 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 event type you want to test and enter the Resource ID to be sent in the notification body (Data ID).

5. Finally, click Send test to verify 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 through 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 reception 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 widens, 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.