In addition to the primary orders topic, Mercado Pago offers optional topics that notify your application about integration management events: account linking via OAuth, buyer-initiated claims, and chargebacks. These notifications complement the main flow and keep your system synchronized with events beyond payment processing.

None of these topics replaces the orders topic or is mandatory. Activate only the ones relevant to your integration.

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

1. Go to 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, and/or Chargebacks.

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

To ensure notifications are configured correctly, simulate receiving them by following the steps below.

1. After configuring your Webhooks, click Simulate notification.

2. On the simulation screen, select the URL to test.

3. Choose the event type you want to test and enter the resource ID to be sent in the notification body (Data ID).

4. 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 received information. This process helps prevent fraud and ensures that only legitimate notifications are processed.

Mercado Pago will send your server a notification similar to the example below. 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, extract the key from the header and compare it with the key provided for your application in Your integrations. 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 so, return an HTTP STATUS 200 or 201 within 22 seconds of receipt.

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.