Las notificaciones Webhooks, también conocidas como devoluciones de llamada web, son mensajes HTTP que Mercado Pago envía a tu servidor cuando ocurre un evento específico en tu integración. En lugar de que tu sistema realice consultas constantes para verificar actualizaciones, los Webhooks transmiten los datos de forma automática mediante una solicitud HTTPS POST.

Sigue los pasos a continuación para recibir notificaciones en tu integración con Checkout Pro. 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.

1. Ingresa a Tus integraciones y selecciona la aplicación integrada con Checkout Pro para la que deseas activar las notificaciones.

2. En el menú de la izquierda, selecciona Webhooks > Configurar notificaciones.

3. Selecciona la pestaña Modo productivo y proporciona una URL HTTPS para recibir notificaciones con tu integración productiva.

4. 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 especificada anteriormente.

5. Por último, haz clic en Guardar configuración. Esto generará una clave secreta exclusiva para la aplicación, que permitirá validar la autenticidad de las notificaciones recibidas, garantizando que hayan sido enviadas por Mercado Pago. Ten en cuenta que esta clave generada no tiene plazo de caducidad y su renovación periódica no es obligatoria, aunque sí recomendada. Para hacerlo, basta con cliquear en el botón Restablecer.

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

1. Después de configurar la URL y el evento, haz clic en Guardar configuración.
2. Luego, haz clic en Simular para probar si la URL indicada está recibiendo las notificaciones correctamente.
3. En la pantalla de simulación, selecciona la URL que se va a probar.
4. 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).

5. 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
Copiar
{
  "action": "order.processed",
  "api_version": "v1",
  "application_id": "123456",
  "date_created": "2025-08-07T18:54:40.851374414Z",
  "id": "123456",
  "live_mode": true,
  "type": "order",
  "user_id": 123456,
  "data": {
    "id": "ORD01JYH1Z1YJN4HZ8J3Q0RB3YP6D"
  }
}

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=ORD01JQ4S4KY8HWQ6NA5PXB65B3D3 y type=order.
• Body: El cuerpo de la notificación contiene información detallada sobre el evento, como action, api_version, application_id, date_created, id, live_mode, type, user_id y data.
• Header: El encabezado contiene metadatos importantes, incluyendo la firma secreta de la notificación x-signature.

http
Copiar
POST /test?data.id=ORD01JQ4S4KY8HWQ6NA5PXB65B3D3&type=order HTTP/1.1
Host: prueba.requestcatcher.com
Accept: */*
Accept-Encoding: *
Connection: keep-alive
Content-Length: 177
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":"123456","date_created":"2025-08-07T18:54:40.851374414Z","id":"123456","live_mode":true,"type":"order","user_id":123456,"data":{"id":"ORD01JYH1Z1YJN4HZ8J3Q0RB3YP6D"}}

A partir de la notificación Webhook recibida, podrás validar la autenticidad de su origen. Mercado Pago siempre incluirá la clave secreta en las notificaciones Webhooks que se recibirán, lo que permitirá validar su autenticidad. Esta clave será enviada en el header x-signature, que será similar al ejemplo a continuación.

plain
Copiar
ts=1742505638683,v1=ced36ab6d33566bb1e16c125819b8d840d6b8ef136b0b9127c76064466f5229b

Para confirmar la validación, es necesario extraer la clave contenida en el header y compararla con la clave proporcionada para tu aplicación en Tus integraciones.

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 esa recepción fue correcta. Para ello, debes devolver un HTTP STATUS 200 (OK) o 201 (CREATED).

El tiempo de espera para esa confirmación será de 22 segundos. Si esa confirmación no es enviada, 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 ocurriendo.

sequenceDiagram
    participant MercadoPago as Mercado Pago
    participant Integrador as Integrador

    MercadoPago->>Integrador: intento: 1. Retraso: 0 minutos
    MercadoPago->>Integrador: intento: 2. Retraso: 15 minutos
    MercadoPago->>Integrador: intento: 3. Retraso: 30 minutos
    MercadoPago->>Integrador: intento: 4. Retraso: 6 horas
    MercadoPago->>Integrador: intento: 5. Retraso: 48 horas
    MercadoPago->>Integrador: intento: 6. Retraso: 96 horas
    MercadoPago->>Integrador: intento: 7. Retraso: 96 horas
    MercadoPago->>Integrador: intento: 8. Retraso: 96 horas

Después de responder a la notificación y confirmar su recepción, puedes obtener toda la información sobre la order notificada enviando un GET al endpoint /v1/orders/{id}API.

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