Recursos para IA

Configurar notificaciones

Las notificaciones Webhooks, también conocidas como devoluciones de llamada web, son un método efectivo que permiten a los servidores de Mercado Pago enviar información en tiempo real cuando ocurre un evento específico relacionado con tu integración. En lugar de que tu sistema realice consultas constantes para verificar actualizaciones, los Webhooks permiten la transmisión de datos de manera pasiva y automática entre Mercado Pago y tu integración a través de una solicitud HTTPS POST, optimizando la comunicación y reduciendo la carga en los servidores.

Configurar Webhooks

A continuación, presentamos un paso a paso para recibir notificaciones de pago en integraciones con Checkout API. Una vez configuradas, las notificaciones Webhook se enviarán siempre que ocurra cualquier actualización sobre el tópico reportado, incluyendo creación y actualización de orders y procesamiento de transacciones.

Ingresa a Integraciones y selecciona la aplicación integrada con Checkout API para la que deseas activar las notificaciones.

Vista general de Integraciones

En el menú lateral, selecciona Configuración de Webhooks.
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.

En caso de ser necesario identificar múltiples cuentas, agrega el parámetro ?client=(nombredelvendedor) al final de la URL indicada para identificar a los vendedores.

Selecciona el evento Order (Mercado Pago) para recibir notificaciones, que serán enviadas en formato JSON a través de un HTTPS POST a la URL configurada para el entorno correspondiente.

Configuración de Webhooks de Checkout API con Orders

Por último, haz clic en Guardar. Esto generará una firma secreta exclusiva para la aplicación, que permitirá validar la autenticidad de las notificaciones recibidas y comprobar que hayan sido enviadas por Mercado Pago. 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.

Simular la recepción de la notificación

Para garantizar que las notificaciones sean configuradas correctamente, es necesario simular su recepción. Para hacerlo, sigue el paso a paso a continuación.

Después de configurar tus Webhooks, haz clic en Simular notificación.
En la pantalla de simulación, selecciona la URL que se va a probar.
A continuación, elige el tipo de evento e ingresa la identificación que se enviará en el cuerpo de la notificación (Data ID).

Simulación de una notificación Webhook

Por último, haz clic en Enviar prueba para verificar la solicitud, la respuesta proporcionada por el servidor y la descripción del evento. Recibirás una respuesta según el ejemplo a continuación, que representa el body de la notificación recibida en tu servidor.

json
{
  "action": "order.processed",
  "api_version": "v1",
  "application_id": "7255333517291496",
  "data": {
    "currency_id": "ARS",
    "external_reference": "ext_ref_1234",
    "id": "ORD01M28P44G5FG8RJPM579EH56FV",
    "items": [
      {
        "external_code": "6754960",
        "quantity": 1
      }
    ],
    "status": "processed",
    "status_detail": "accredited",
    "total_amount": "200.00",
    "total_paid_amount": "200.00",
    "transactions": {
      "payments": [
        {
          "amount": "200.00",
          "id": "PAY01M28P44GDSD4JYTSK5SYZT6BH",
          "paid_amount": "200.00",
          "payment_method": {
            "id": "master",
            "installments": 1,
            "type": "credit_card"
          },
          "reference": {
            "id": "000fkonfh0"
          },
          "status": "processed",
          "status_detail": "accredited"
        }
      ]
    },
    "type": "online",
    "version": 1
  },
  "date_created": "2026-09-11T16:52:02.736053815Z",
  "live_mode": true,
  "type": "order",
  "user_id": "11111111"
}

Si por algún motivo no estás recibiendo las notificaciones de Mercado Pago, puedes alternativamente obtener la información sobre el recurso que no fue notificado enviando una solicitud al endpoint /v1/orders/{id}GET. El uso de este método no es recomendado, por lo que adicionalmente sugerimos entrar en contacto con Soporte.

Monitorear notificaciones

Para consultar el funcionamiento de las notificaciones, 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.

En esta pantalla puedes filtrar los envíos, consultar su fecha, estado de entrega, acción, evento e ID del recurso, y revisar las métricas de entrega y tiempo de respuesta. En Prueba, los datos se actualizan en tiempo real.

Monitoreo de notificaciones Webhook

Para consultar los datos del envío y el cuerpo de la notificación, selecciona una notificación de la tabla para abrir su detalle.

Detalle de una notificación Webhook

Para reenviar una o varias notificaciones, selecciónalas en la tabla y haz clic en Reenviar notificaciones.

Validar origen de la notificación

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 similar al ejemplo a continuación para una alerta del tópico order. En este ejemplo, se incluye la notificación completa, que contiene los query params, el body y el header de la notificación.

Query params: Son parámetros de consulta que acompañan la URL. En el ejemplo, tenemos data.id=ORD01M28P44G5FG8RJPM579EH56FV y type=order.
Body: El cuerpo de la notificación contiene información detallada sobre el evento y la order, incluyendo action, data.status, data.status_detail y data.transactions.payments.
Header: El encabezado contiene metadatos importantes, incluyendo la firma secreta de la notificación x-signature.

plain
POST /test?data.id=ORD01M28P44G5FG8RJPM579EH56FV&type=order HTTP/1.1
Host: prueba.requestcatcher.com
Accept: */*
Accept-Encoding: *
Connection: keep-alive
Content-Type: application/json
Newrelic: eyJ2IjpbMCwxXSwiZCI6eyJ0eSI6IkFwcCIsImFjIjoiOTg5NTg2IiwiYXAiOiI5NjA2MzYwOTQiLCJ0eCI6ImY4MzljZjg4ODg2MGRmZTIiLCJ0ciI6ImMwOGMwZGMyMjNjZDY2YjJkZWQwMjUxZmYxNWNiNGQ1IiwicHIiOjEuMjUwMzIsInNhIjp0cnVlLCJ0aSI6MTc0Mjg0MjU4MDE2NCwiaWQiOiIxOGI2NDcxNjNkNzI3NjU4IiwidGsiOiIxNzA5NzA3In19=
Traceparent: 00-c08c0dc223cd66b2ded0251ff15cb4d5-18b647163d727658-01
Tracestate: 1709707@nr=0-0-989586-960636094-18b647163d727658-f839cf888860dfe2-1-1.250320-1742842580164
User-Agent: restclient-node/4.15.3
X-Request-Id: 2066ca19-c6f1-498a-be75-1923005edd06
X-Rest-Pool-Name: /services/webhooks.js
X-Retry: 0
X-Signature: ts=1742505638683,v1=ced36ab6d33566bb1e16c125819b8d840d6b8ef136b0b9127c76064466f5229b
X-Socket-Timeout: 22000
{"action":"order.processed","api_version":"v1","application_id":"7255333517291496","data":{"currency_id":"ARS","external_reference":"ext_ref_1234","id":"ORD01M28P44G5FG8RJPM579EH56FV","items":[{"external_code":"6754960","quantity":1}],"status":"processed","status_detail":"accredited","total_amount":"200.00","total_paid_amount":"200.00","transactions":{"payments":[{"amount":"200.00","id":"PAY01M28P44GDSD4JYTSK5SYZT6BH","paid_amount":"200.00","payment_method":{"id":"master","installments":1,"type":"credit_card"},"reference":{"id":"000fkonfh0"},"status":"processed","status_detail":"accredited"}]},"type":"online","version":1},"date_created":"2026-09-11T16:52:02.736053815Z","live_mode":true,"type":"order","user_id":"11111111"}

A partir de la notificación Webhook recibida, podrás validar la autenticidad de su origen a través la clave secreta en las notificaciones Webhooks que serán recibidas. Esta clave será enviada en el header x-signature, que será similar al ejemplo debajo.

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.

Los SDKs oficiales implementan verificación de firma basada en HMAC (HMAC-based Webhook Signature Verification) para autenticar el origen de cada notificación recibida.

Para obtener tu clave secreta (secret), abre la aplicación y, en el menú lateral, selecciona Configuración de Webhooks. Luego, revela la Firma secreta.

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

Acciones necesarias después de recibir la notificación

Cuando recibes una notificación en tu plataforma, Mercado Pago espera una respuesta para validar que esa recepción fue correcta. Para eso, debes devolver un HTTP STATUS 200 (OK) o 201 (CREATED).

El tiempo de espera para esa confirmación será de 22 segundos. Si no se envía esta respuesta, el sistema entenderá que la notificación no fue recibida y realizará un nuevo intento de envío cada 15 minutos, hasta que reciba la respuesta. Después del tercer intento, el plazo será prorrogado, pero los envíos continuarán sucediendo.

Después de responder a la notificación y confirmar su recepción, puedes obtener toda la información sobre el recurso notificado enviando una solicitud al endpoint /v1/orders/{id}GET.

Para identificar una order vencida, verifica si la notificación contiene data.status_detail: expired. En este caso, el campo action devuelve canceled o failed, según el estado final de la order.

Con esta información podrás realizar las actualizaciones necesarias en tu plataforma, como actualizar un pago aprobado.

AnteriorPagos únicos con tarjeta guardadaProcesa pagos únicos sin necesidad de usar el CVV de la tarjeta

PróximoConfigurar notificaciones de perfiles de pagoConfigura la recepción de notificaciones de Mercado Pago para mantener actualizados los perfiles de pago.