Notificaciones
Las notificaciones son mensajes enviados por el servidor de Mercado Pago a partir de eventos realizados en tu aplicaciĂłn.
Webhooks (también conocido como devolución de llamada web) utiliza HTTP REST para notificar instantåneamente las actualizaciones y ofrece mayor seguridad en la integración mediante la clave secreta, un método de validación para garantizar que las notificaciones recibidas fueron enviadas por Mercado Pago.
Una vez configurada, una notificaciĂłn Webhook serĂĄ enviada cada vez que ocurra uno o mĂĄs eventos registrados, evitando la necesidad de verificaciones constantes y, consecuentemente, previniendo la sobrecarga del sistema y la pĂ©rdida de datos en situaciones crĂticas.
Configurar notificaciones Webhooks
Las notificaciones Webhooks se pueden configurar para una o mås aplicaciones creadas en Tus integraciones. También es posible configurar una URL de prueba que, junto con las credenciales de prueba, permitirå verificar el correcto funcionamiento de las notificaciones previo a salir a producción.
Para configurar notificaciones Webhooks de Order, sigue los pasos a continuaciĂłn.
- Ingresa a Tus Integraciones y selecciona la aplicaciĂłn para la que deseas activar las notificaciones. En caso de que aĂșn no hayas creado una aplicaciĂłn, accede a la documentaciĂłn sobre el Panel del Desarrollador y sigue las instrucciones para poder hacerlo.
- En el menĂș de la izquierda, selecciona Webhooks > Configurar notificaciones, y configura las URLs que serĂĄn utilizadas para recibirlas. Recomendamos utilizar dos URLs diferentes para el modo de pruebas y el modo producciĂłn:
- URL modo pruebas: proporciona una URL que permita probar el correcto funcionamiento de las notificaciones de la aplicaciĂłn durante la etapa de desarrollo.
- URL modo producciĂłn: proporciona una URL para recibir notificaciones con tu integraciĂłn productiva. Estas notificaciones deberĂĄn ser configuradas con tus credenciales productivas.
- Selecciona el evento Order (Mercado Pago) para recibir notificaciones, que serĂĄn enviadas en formato
JSON
a través de unHTTP POST
a la URL especificada anteriormente. Un evento puede ser cualquier actualizaciĂłn sobre el tĂłpico reportado, incluyendo creaciĂłn y actualizaciĂłn de orders, y procesamiento de transacciones. - Por Ășltimo, haz clic en Guardar. 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.
Validar origen de una notificaciĂłn
Las notificaciones enviadas por Mercado Pago serĂĄn semejantes al siguiente ejemplo para un alerta del tĂłpico order
:
json
{
"action": "processed",
"type": "order",
"user_id": "123456",
"application_id": "789012",
"live_mode": true,
"api_version": "v1",
"date_created": "2024-01-01T00:00:00Z",
"data": {
"id": "01J35M8KHVFY0GQGDZJ94QXKMJ",
"type": "online",
"external_reference": "ext_ref_1234",
"status": "processed",
"version": 1,
"transactions": {
"payments": [
{
"id": "pay_01J3E4R55CTGYCEXCKSQB6RKDE",
"status": "processed",
"payment_method": {
"id": "visa",
"type": "credit_card",
"installments": 1
}
}
]
}
}
}
Mercado Pago siempre incluirĂĄ la clave secreta en las notificaciones Webhooks que serĂĄn recibidas, lo que permitirĂĄ validar su autenticidad para proporcionar mayor seguridad y prevenir posibles fraudes.
Esta clave serĂĄ enviada en el header x-signature
, que serĂĄ similar al ejemplo debajo.
x-signature
`ts=1704908010,v1=618c85345248dd820d5fd456117c2ab2ef8eda45a0282ff693eac24131a5e839`
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 Tus integraciones. Esto podrĂĄ ser hecho siguiendo el paso a paso a continuaciĂłn.
- Para extraer el timestamp (
ts
) y la clave del headerx-signature
, divide el contenido del header por el carĂĄcter,
, lo que resultarĂĄ en una lista de elementos. El valor para el prefijots
es el timestamp (en milisegundos) de la notificaciĂłn yv1
es la clave encriptada. Siguiendo el ejemplo presentado anteriormente,ts=1704908010
yv1=618c85345248dd820d5fd456117c2ab2ef8eda45a0282ff693eac24131a5e839
. - Utilizando el template a continuaciĂłn, sustituye los parĂĄmetros con los datos recibidos en tu notificaciĂłn.
template
id:[data.id_url];request-id:[x-request-id_header];ts:[ts_header];
- Los parĂĄmetros con el sufijo
_url
provienen de query params. Ejemplo:[data.id_url]
se sustituirĂĄ por el valor correspondiente al ID del evento (data.id
). Este query param puede ser hallado en la notificaciĂłn recibida. [ts_header]
serĂĄ el valorts
extraĂdo del headerx-signature
.[x-request-id_header]
deberĂĄ ser sustituido por el valor recibido en el headerx-request-id
.
- En Tus integraciones, selecciona la aplicaciĂłn integrada, ve a la secciĂłn de Webhooks y revela la clave secreta generada.
- Genera la contraclave para la validaciĂłn. Para hacer esto, calcula un HMAC con la funciĂłn de
hash SHA256
en base hexadecimal, utilizando la clave 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()))
- Finalmente, compara la clave generada con la clave extraĂda del header, asegurĂĄndote de que tengan una correspondencia exacta. AdemĂĄs, puedes usar el timestamp extraĂdo del header para compararlo con un timestamp generado en el momento de la recepciĂłn de la notificaciĂłn, con el fin de establecer una tolerancia de demora en la recepciĂłn del mensaje.
A continuaciĂłn, puedes ver ejemplos de cĂłdigo completo:
<?php
// Obtain the x-signature value from the header
$xSignature = $_SERVER['HTTP_X_SIGNATURE'];
$xRequestId = $_SERVER['HTTP_X_REQUEST_ID'];
// Obtain Query params related to the request URL
$queryParams = $_GET;
// Extract the "data.id" from the query params
$dataID = isset($queryParams['data.id']) ? $queryParams['data.id'] : '';
// Separating the x-signature into parts
$parts = explode(',', $xSignature);
// Initializing variables to store ts and hash
$ts = null;
$hash = null;
// Iterate over the values to obtain ts and v1
foreach ($parts as $part) {
// Split each part into key and value
$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;
}
}
}
// Obtain the secret key for the user/application from Mercadopago developers site
$secret = "your_secret_key_here";
// Generate the manifest string
$manifest = "id:$dataID;request-id:$xRequestId;ts:$ts;";
// Create an HMAC signature defining the hash type and the key as a byte array
$sha = hash_hmac('sha256', $manifest, $secret);
if ($sha === $hash) {
// HMAC verification passed
echo "HMAC verification passed";
} else {
// HMAC verification failed
echo "HMAC verification failed";
}
?>
// Obtain the x-signature value from the header
const xSignature = headers['x-signature']; // Assuming headers is an object containing request headers
const xRequestId = headers['x-request-id']; // Assuming headers is an object containing request headers
// Obtain Query params related to the request URL
const urlParams = new URLSearchParams(window.location.search);
const dataID = urlParams.get('data.id');
// Separating the x-signature into parts
const parts = xSignature.split(',');
// Initializing variables to store ts and hash
let ts;
let hash;
// Iterate over the values to obtain ts and v1
parts.forEach(part => {
// Split each part into key and value
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;
}
}
});
// Obtain the secret key for the user/application from Mercadopago developers site
const secret = 'your_secret_key_here';
// Generate the manifest string
const manifest = `id:${dataID};request-id:${xRequestId};ts:${ts};`;
// Create an HMAC signature
const hmac = crypto.createHmac('sha256', secret);
hmac.update(manifest);
// Obtain the hash result as a hexadecimal string
const sha = hmac.digest('hex');
if (sha === hash) {
// HMAC verification passed
console.log("HMAC verification passed");
} else {
// HMAC verification failed
console.log("HMAC verification failed");
}
import hashlib
import hmac
import urllib.parse
# Obtain the x-signature value from the header
xSignature = request.headers.get("x-signature")
xRequestId = request.headers.get("x-request-id")
# Obtain Query params related to the request URL
queryParams = urllib.parse.parse_qs(request.url.query)
# Extract the "data.id" from the query params
dataID = queryParams.get("data.id", [""])[0]
# Separating the x-signature into parts
parts = xSignature.split(",")
# Initializing variables to store ts and hash
ts = None
hash = None
# Iterate over the values to obtain ts and v1
for part in parts:
# Split each part into key and value
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
# Obtain the secret key for the user/application from Mercadopago developers site
secret = "your_secret_key_here"
# Generate the manifest string
manifest = f"id:{dataID};request-id:{xRequestId};ts:{ts};"
# Create an HMAC signature defining the hash type and the key as a byte array
hmac_obj = hmac.new(secret.encode(), msg=manifest.encode(), digestmod=hashlib.sha256)
# Obtain the hash result as a hexadecimal string
sha = hmac_obj.hexdigest()
if sha == hash:
# HMAC verification passed
print("HMAC verification passed")
else:
# HMAC verification failed
print("HMAC verification failed")
import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"fmt"
"net/http"
"strings"
)
func main() {
http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
// Obtain the x-signature value from the header
xSignature := r.Header.Get("x-signature")
xRequestId := r.Header.Get("x-request-id")
// Obtain Query params related to the request URL
queryParams := r.URL.Query()
// Extract the "data.id" from the query params
dataID := queryParams.Get("data.id")
// Separating the x-signature into parts
parts := strings.Split(xSignature, ",")
// Initializing variables to store ts and hash
var ts, hash string
// Iterate over the values to obtain ts and v1
for _, part := range parts {
// Split each part into key and value
keyValue := strings.SplitN(part, "=", 2)
if len(keyValue) == 2 {
key := strings.TrimSpace(keyValue[0])
value := strings.TrimSpace(keyValue[1])
if key == "ts" {
ts = value
} else if key == "v1" {
hash = value
}
}
}
// Get secret key/token for specific user/application from Mercadopago developers site
secret := "your_secret_key_here"
// Generate the manifest string
manifest := fmt.Sprintf("id:%v;request-id:%v;ts:%v;", dataID, xRequestId, ts)
// Create an HMAC signature defining the hash type and the key as a byte array
hmac := hmac.New(sha256.New, []byte(secret))
hmac.Write([]byte(manifest))
// Obtain the hash result as a hexadecimal string
sha := hex.EncodeToString(hmac.Sum(nil))
if sha == hash {
// HMAC verification passed
fmt.Println("HMAC verification passed")
} else {
// HMAC verification failed
fmt.Println("HMAC verification failed")
}
})
}
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 las URLs y los Eventos, haz clic en Guardar para guardar la configuración.
- Luego, haz clic en Simular para probar si la URL indicada estĂĄ recibiendo las notificaciones correctamente.
- En la pantalla de simulaciĂłn, selecciona la URL que se va a probar, que puede ser la URL de prueba o la de producciĂłn.
- A continuaciĂłn, elige Order (Mercado Pago) como el tipo de evento e ingresa la identificaciĂłn que se enviarĂĄ en el cuerpo de la notificaciĂłn.
- Por Ășltimo, haz clic en Enviar prueba para verificar la solicitud, la respuesta proporcionada por el servidor y la descripciĂłn del evento.
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.
Luego de responder la notificaciĂłn, confirmando su recibimiento, puedes obtener toda la informaciĂłn sobre el recurso notificado enviando un GET al endpoint /v1/orders/{id}.
Con esta informaciĂłn podrĂĄs realizar las actualizaciones necesarias en tu plataforma, como actualizar un pago aprobado.