Configure optional notifications

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

1. Go to Integrations and select the application for which you want to activate notifications.

2. In the side menu, select Webhooks configuration.

3. In the Test / Production switch at the top of the screen, select Test and enter the HTTPS URL to receive test notifications. If you want to configure production notifications, select Production and enter the production HTTPS URL.

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. This will generate a secret signatureSignature associated with the Webhooks configuration and used to validate the authenticity of notifications sent by Mercado Pago. You can find it under the application's Webhooks configuration.Configure Webhooks for your application. The signature does not expire, and periodic renewal is not mandatory, although it is recommended. To renew it, click Reset secret signature.

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

1. After configuring your Webhooks, click Simulate notification.
2. On the simulation screen, select the URL to be tested.
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.

Optional events are also available in the application's monitoring view. To review them, open the application and select the Webhooks tab under Home. Use the Test / Production switch to view notifications for the selected environment.

From there, you can filter notification deliveries, review their date, delivery status, action, event, and resource ID, check delivery and response-time metrics, open the details to view the notification body, and resend it when necessary. In Test, data updates in real time.

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
POST /?data.id=123456789&type=mp-connect HTTP/1.1
Host: test-optional-nots.requestcatcher.com
Accept: */*
Accept-Encoding: *
Connection: keep-alive
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
ts=1742505638683,v1=ced36ab6d33566bb1e16c125819b8d840d6b8ef136b0b9127c76064466f5229b

To confirm the validation, extract the key from the header and compare it with the key provided for your application under Webhooks configuration.

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 sending a request to the Refund orderPOST endpoint.
• For chargeback management, see the documentation.