Configurar notificaciones opcionales

Sigue los pasos a continuación para activar los tópicos opcionales en tu integración.

1. Accede a Integraciones y selecciona la aplicación para la que deseas activar las notificaciones.

2. En el menú lateral, selecciona Configuración de Webhooks.

3. En el switch Prueba / Producción de la parte superior, selecciona Prueba e ingresa la URL HTTPS para recibir notificaciones de prueba. Si quieres configurar notificaciones de producción, selecciona Producción e ingresa la URL HTTPS de producción.

4. En la sección de tópicos opcionales, selecciona los eventos que deseas activar: Vinculación de aplicaciones, Reclamos, Contracargos y/o Alertas de fraude.

5. Por último, haz clic en Guardar. Esto generará una firma secretaFirma asociada a la configuración de Webhooks que se utiliza para validar la autenticidad de las notificaciones enviadas por Mercado Pago. Puedes consultarla en Configuración de Webhooks de la aplicación.Configurar Webhooks para tu aplicación. La firma no tiene plazo de caducidad y su renovación periódica no es obligatoria, aunque sí recomendada. Para renovarla, haz clic en Restablecer firma secreta.

Para garantizar que las notificaciones estén configuradas correctamente, simula su recepción siguiendo el paso a paso a continuación.

1. Después de configurar tus Webhooks, haz clic en Simular notificación.
2. En la pantalla de simulación, selecciona la URL que se va a probar.
3. Elige el tipo de evento que deseas probar e ingresa el ID del recurso que se enviará en el cuerpo de la notificación (Data ID).
4. Por último, haz clic en Enviar prueba para verificar la solicitud, la respuesta del servidor y la descripción del evento.

Los eventos opcionales también están disponibles en el monitoreo de la aplicación. Para consultarlos, abre la aplicación y, en Inicio, selecciona la pestaña Webhooks. Utiliza el switch Prueba / Producción para consultar las notificaciones del entorno seleccionado.

Allí puedes filtrar los envíos, consultar su fecha, estado de entrega, acción, evento e ID del recurso, revisar las métricas de entrega y tiempo de respuesta, abrir el detalle para ver el cuerpo de la notificación y reenviarla cuando sea necesario. En Prueba, los datos se actualizan en tiempo real.

La validación del origen de una notificación es fundamental para asegurar la seguridad y la autenticidad de la información recibida. Este proceso ayuda a prevenir fraudes y garantiza que solo las notificaciones legítimas sean procesadas.

Mercado Pago enviará a tu servidor una notificación que incluye los siguientes componentes:

• Query params: Acompañan la URL de la solicitud. Contienen data.id con el identificador del recurso notificado y type con el nombre del tópico.
• Body: Contiene los detalles del evento notificado, como action, api_version, application_id, date_created, id, live_mode, type, user_id y data.
• Header: Incluye la firma secreta x-signature, que permite validar la autenticidad de la notificación.

A continuación, se muestran ejemplos de las notificaciones para cada tópico.

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}

A partir de la notificación recibida, podrás validar la autenticidad de su origen a través de la clave secreta. Esta clave será enviada en el header x-signature, con el siguiente formato:

plain
ts=1742505638683,v1=ced36ab6d33566bb1e16c125819b8d840d6b8ef136b0b9127c76064466f5229b

Para confirmar la validación, es necesario extraer la clave contenida en el header y compararla con la clave otorgada para tu aplicación en Configuración de Webhooks.

Sigue uno de los enfoques a continuación para validar la autenticidad de la notificación.

<?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

Cuando recibes una notificación en tu plataforma, Mercado Pago espera una respuesta para validar que la recepción fue correcta. Para eso, devuelve un HTTP STATUS 200 o 201 dentro de los 22 segundos siguientes a la recepción.

Recomendamos que primero respondas con un 200 o 201, y que luego proceses la notificación en el servidor, para evitar notificaciones duplicadas.

Si no se envía esta respuesta, el sistema realizará nuevos intentos de envío cada 15 minutos. Después de los primeros fallos, el intervalo se amplía progresivamente, pero las entregas continúan hasta que la notificación sea confirmada.

Adicionalmente, ten en cuenta:

• Al recibir una alerta de fraude, debes reembolsar el pago sin entregar el pedido enviando una solicitud al endpoint Reembolsar orderPOST.
• Para la gestión de contracargos, consulta la documentación.