Configurar notificações

A seguir, apresentaremos um passo a passo para poder receber notificações em integrações com Wallet Connect. Uma vez configuradas, as notificações Webhook serão enviadas sempre que ocorrer qualquer atualização sobre os tópicos reportados, incluindo criação e atualização de orders, processamento de transações e eventos de vinculação.

1. Acesse Suas integrações e selecione a aplicação criada pela equipe responsável por sua integração com Wallet Connect, a qual deseja ativar as notificações.

2. No menu à esquerda, selecione Webhooks > Configurar notificações.

3. Selecione a aba Modo de produção e forneça uma URL HTTPS para receber notificações com sua integração produtiva.

4. Selecione os eventos para receber notificações:

   • Order (Mercado Pago): para receber notificações de pagamentos realizados com a Orders API.
   • Wallet Connect: para receber notificações de eventos de vinculação (confirmação e cancelamento).

5. Por fim, clique em Salvar configuração. Isso gerará uma chave secreta exclusiva para a aplicação, que permitirá validar a autenticidade das notificações recebidas, garantindo que tenham sido enviadas pelo Mercado Pago. Tenha em mente que esta chave gerada não tem prazo de validade e sua renovação periódica não é obrigatória, embora seja recomendada. Para isso, basta clicar no botão Redefinir.

Para garantir que as notificações sejam configuradas corretamente, é necessário simular sua recepção. Para isso, siga o passo a passo abaixo.

1. Após configurar a URL e os eventos, clique em Salvar configuração.
2. Depois, clique em Simular para testar se a URL indicada está recebendo as notificações corretamente.
3. Na tela de simulação, selecione a URL que será testada.
4. Em seguida, selecione o tipo de evento e insira a identificação que será enviada no corpo da notificação (Data ID).
5. Por fim, clique em Enviar teste para verificar a solicitação, a resposta fornecida pelo servidor e a descrição do evento.

A validação da origem de uma notificação é fundamental para assegurar a segurança e a autenticidade das informações recebidas. Este processo ajuda a prevenir fraudes e garante que somente as notificações legítimas sejam processadas.

O Mercado Pago enviará ao seu servidor uma notificação similar ao exemplo abaixo para um alerta do tema order. Neste exemplo, está incluída a notificação completa, que contém os query params, o body e o header da notificação.

• Query params: São parâmetros de consulta que acompanham a URL. No exemplo, temos data.id=ORD01JQ4S4KY8HWQ6NA5PXB65B3D3 e type=order.
• Body: O corpo da notificação contém informações detalhadas sobre o evento, como action, api_version, application_id, date_created, id, live_mode, type, user_id e data.
• Header: O cabeçalho contém metadados importantes, incluindo a assinatura secreta da notificação x-signature.

plain
POST /test?data.id=ORD01JQ4S4KY8HWQ6NA5PXB65B3D3&type=order HTTP/1.1
Host: prueba.requestcatcher.com
Accept: */*
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 da notificação Webhook recebida, você poderá validar a autenticidade de sua origem. O Mercado Pago sempre incluirá a chave secreta nas notificações Webhooks que serão recebidas, o que permitirá validar sua autenticidade. Esta chave será enviada no header x-signature.

Para confirmar a validação, é necessário extrair a chave contida no cabeçalho e compará-la com a chave fornecida para sua aplicação em Suas integrações. Para isso, siga o passo a passo abaixo.

1. Para extrair o timestamp (ts) e a chave (v1) do header x-signature, divida o conteúdo do header pelo caractere ",". O valor para o prefixo ts é o timestamp (em milissegundos) da notificação e v1 é a chave encriptada.
2. Utilizando o template abaixo, substitua os parâmetros com os dados recebidos na sua notificação.

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

3. Em Suas integrações, selecione a aplicação integrada, clique em Webhooks > Configurar notificação e revele a chave secreta gerada.
4. Gere a contrachave para validação. Para fazer isso, calcule um HMAC com a função de hash SHA256 em base hexadecimal, utilizando a assinatura secreta como chave e o template com os valores como mensagem.

$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, compare a chave gerada com a chave extraída do header, assegurando-se de que tenham uma correspondência exata.

Veja exemplos de códigos completos abaixo:

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

Quando você recebe uma notificação em sua plataforma, o Mercado Pago espera uma resposta para validar que essa recepção foi correta. Para isso, você deve devolver um HTTP STATUS 200 (OK) ou 201 (CREATED).

O tempo de espera para essa confirmação será de 22 segundos. Se essa confirmação não for enviada, o sistema entenderá que a notificação não foi recebida e realizará uma nova tentativa de envio a cada 15 minutos, até que receba a resposta.

Após responder à notificação e confirmar seu recebimento, você pode obter todas as informações sobre o recurso notificado enviando uma solicitação ao endpoint /v1/orders/{id}GET.

Conheça os eventos de vinculação e pagamento que geram notificações Webhook e consulte exemplos dos dados enviados em cada caso.

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"
  }
}

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": "canceled"
  }
}