Configurar notificaciones

Las notificaciones Webhooks, también conocidas como devoluciones de llamada web, son un método eficaz que permite 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, presentaremos un paso a paso para recibir notificaciones en integraciones con Wallet Connect. Una vez configuradas, las notificaciones Webhook se enviarán siempre que ocurra cualquier actualización sobre los tópicos reportados, incluyendo creación y actualización de orders, procesamiento de transacciones y eventos de vinculación.

1. Accede a Tus integraciones y selecciona la aplicación creada por el equipo responsable de tu integración con Wallet Connect, para la cual deseas activar las notificaciones.

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

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

4. Selecciona los eventos para recibir notificaciones:

   • Order (Mercado Pago): para recibir notificaciones de pagos realizados con Orders API.
   • Wallet Connect: para recibir notificaciones de eventos de vinculación (confirmación y cancelación).

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 fecha de vencimiento y su renovación periódica no es obligatoria, aunque sí recomendada. Para ello, haz clic en el botón Restablecer.

Simular la recepción de la notificación

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

1. Después de configurar la URL y los eventos, 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 será probada.
4. A continuación, selecciona 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 del servidor y la descripción del evento.

Validar el origen de la notificación

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

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 a la URL.
• Body: El cuerpo de la notificación contiene información detallada sobre el evento.
• Header: El encabezado contiene metadatos importantes, incluyendo la firma secreta x-signature.

plain
POST /test?data.id=ORD01JQ4S4KY8HWQ6NA5PXB65B3D3&type=order HTTP/1.1
Host: prueba.requestcatcher.com
Content-Type: application/json
X-Request-Id: 2066ca19-c6f1-498a-be75-1923005edd06
X-Signature: ts=1742505638683,v1=ced36ab6d33566bb1e16c125819b8d840d6b8ef136b0b9127c76064466f5229b
{"action":"order.action_required","api_version":"v1","application_id":"76506430185983","date_created":"2021-11-01T02:02:02Z","id":"123456","live_mode":false,"type":"order","user_id":2025701502,"data":{"id":"ORD01JQ4S4KY8HWQ6NA5PXB65B3D3"}}

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 reciban, lo que permitirá validar su autenticidad. Esta clave se enviará en el header x-signature.

Para confirmar la validación, es necesario extraer la clave contenida en el encabezado y compararla con la clave proporcionada para tu aplicación en Tus integraciones. Para ello, sigue el paso a paso a continuación.

1. Para extraer el timestamp (ts) y la clave (v1) del header x-signature, divide el contenido del header por el carácter ",". El valor para el prefijo ts es el timestamp (en milisegundos) de la notificación y v1 es la clave cifrada.
2. Utilizando el template a continuación, reemplaza los parámetros con los datos recibidos en tu notificación.

plain
id:[data.id_url];request-id:[x-request-id_header];ts:[ts_header];

3. En Tus integraciones, selecciona la aplicación integrada, haz clic en Webhooks > Configurar notificación y revela la clave secreta generada.
4. Genera la contraclave para validación. Para ello, calcula un HMAC con la función de hash SHA256 en base hexadecimal, usando la firma secreta como clave y el template con los valores como mensaje.

$cyphedSignature = hash_hmac('sha256', $data, $key);

const crypto = require('crypto');
const cyphedSignature = crypto
    .createHmac('sha256', secret)
    .update(signatureTemplateParsed)
    .digest('hex');

String cyphedSignature = new HmacUtils("HmacSHA256", secret).hmacHex(signedTemplate);

import hashlib, hmac, binascii

cyphedSignature = binascii.hexlify(hmac_sha256(secret.encode(), signedTemplate.encode()))

5. Finalmente, compara la clave generada con la clave extraída del header, asegurándote de que tengan una correspondencia exacta.

Consulta ejemplos de códigos completos a continuación:

<?php
$xSignature = $_SERVER['HTTP_X_SIGNATURE'];
$xRequestId = $_SERVER['HTTP_X_REQUEST_ID'];
$queryParams = $_GET;
$dataID = isset($queryParams['data.id']) ? $queryParams['data.id'] : '';
$parts = explode(',', $xSignature);
$ts = null;
$hash = null;
foreach ($parts as $part) {
    $keyValue = explode('=', $part, 2);
    if (count($keyValue) == 2) {
        $key = trim($keyValue[0]);
        $value = trim($keyValue[1]);
        if ($key === "ts") {
            $ts = $value;
        } elseif ($key === "v1") {
            $hash = $value;
        }
    }
}
$secret = "your_secret_key_here";
$manifest = "id:$dataID;request-id:$xRequestId;ts:$ts;";
$sha = hash_hmac('sha256', $manifest, $secret);
if ($sha === $hash) {
    echo "HMAC verification passed";
} else {
    echo "HMAC verification failed";
}
?>

const xSignature = headers['x-signature'];
const xRequestId = headers['x-request-id'];
const urlParams = new URLSearchParams(window.location.search);
const dataID = urlParams.get('data.id');
const parts = xSignature.split(',');
let ts;
let hash;
parts.forEach(part => {
    const [key, value] = part.split('=');
    if (key && value) {
        const trimmedKey = key.trim();
        const trimmedValue = value.trim();
        if (trimmedKey === 'ts') {
            ts = trimmedValue;
        } else if (trimmedKey === 'v1') {
            hash = trimmedValue;
        }
    }
});
const secret = 'your_secret_key_here';
const manifest = `id:${dataID};request-id:${xRequestId};ts:${ts};`;
const hmac = crypto.createHmac('sha256', secret);
hmac.update(manifest);
const sha = hmac.digest('hex');
if (sha === hash) {
    console.log("HMAC verification passed");
} else {
    console.log("HMAC verification failed");
}

import hashlib
import hmac
import urllib.parse

xSignature = request.headers.get("x-signature")
xRequestId = request.headers.get("x-request-id")
queryParams = urllib.parse.parse_qs(request.url.query)
dataID = queryParams.get("data.id", [""])[0]
parts = xSignature.split(",")
ts = None
hash = None
for part in parts:
    keyValue = part.split("=", 1)
    if len(keyValue) == 2:
        key = keyValue[0].strip()
        value = keyValue[1].strip()
        if key == "ts":
            ts = value
        elif key == "v1":
            hash = value
secret = "your_secret_key_here"
manifest = f"id:{dataID};request-id:{xRequestId};ts:{ts};"
hmac_obj = hmac.new(secret.encode(), msg=manifest.encode(), digestmod=hashlib.sha256)
sha = hmac_obj.hexdigest()
if sha == hash:
    print("HMAC verification passed")
else:
    print("HMAC verification failed")

Acciones necesarias tras recibir la notificación

Cuando recibes una notificación en tu plataforma, Mercado Pago espera una respuesta para validar que la 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 se envía, el sistema entenderá que la notificación no fue recibida y realizará un nuevo intento de envío cada 15 minutos, hasta recibir la respuesta.

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

Tipos de eventos

Vinculaciones

Hay dos tipos de eventos relacionados con la vinculación, notificados por el tópico wallet_connect:

json
{
  "id": "22abcd1235ed497f945f755fcaba3c6c",
  "type": "wallet_connect",
  "entity": "agreement",
  "action": "status.updated",
  "date": "2021-09-30T23:24:44Z",
  "model_version": 1,
  "version": 0,
  "data": {
    "id": "22abcd1235ed497f945f755fcaba3c6c",
    "status": "confirmed_by_user"
  }
}

Pagos (Orders API)

Los webhooks de pago son notificados por el tópico order. Los tipos posibles son order_processed, order_failed y order_refunded.

json
{
  "action": "order_processed",
  "api_version": "v1",
  "application_id": "76506430185983",
  "date_created": "2021-11-01T02:02:02Z",
  "id": "123456",
  "live_mode": true,
  "type": "order",
  "user_id": 2025701502,
  "data": {
    "id": "ORDBTA01KJZ06DEJX3DMY26FAB44BXNN"
  }
}