Configurar notificações opcionais

Além do tópico primário de orders, o Mercado Pago oferece tópicos opcionais que notificam sua aplicação sobre eventos de gestão da integração: vinculação de contas via OAuth, reclamações iniciadas por compradores, contestações e alertas de fraude. Essas notificações complementam o fluxo principal e permitem que você mantenha seu sistema sincronizado com eventos que vão além do processamento de pagamentos.

Nenhum desses tópicos substitui o tópico de orders nem é obrigatório. Ative apenas os que forem relevantes para sua integração.

Tópicos disponíveis

Configurar Webhooks

Siga os passos abaixo para ativar os tópicos opcionais na sua integração.

1. Acesse Suas integrações e selecione a aplicação para a qual deseja ativar as notificações.

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

3. Selecione a aba Modo produtivo e forneça uma URL HTTPS para receber notificações.

4. Na seção de tópicos opcionais, selecione os eventos que deseja ativar: Vinculação de aplicações, Reclamações, Contestações e/ou Alertas de fraude.

5. Por último, clique em Salvar configuração. Isso irá gerar uma chave secretaChave usada para validar a autenticidade de cada notificação recebida. para sua aplicação. Observe que essa chave não tem prazo de validade e a renovação periódica não é obrigatória, embora seja recomendada. Para isso, basta clicar no botão Redefinir.

Simular o recebimento da notificação

Para garantir que as notificações estejam configuradas corretamente, simule o recebimento seguindo o passo a passo abaixo.

1. Após configurar a URL e os eventos, clique em Salvar configuração.

2. Em seguida, clique em Simular para verificar que a URL indicada está recebendo as notificações corretamente.

3. Na tela de simulação, selecione a URL a ser testada.

4. Escolha o tipo de evento que deseja testar e insira o ID do recurso que será enviado no corpo da notificação (Data ID).

5. Por último, clique em Enviar teste para verificar a requisição, a resposta do servidor e a descrição do evento.

Validar a origem da notificação

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

O Mercado Pago enviará ao seu servidor uma notificação que inclui os seguintes componentes:

• Query params: Acompanham a URL da solicitação. Contêm data.id com o identificador do recurso notificado e type com o nome do tópico.
• Body: Contém os detalhes do evento notificado, como action, api_version, application_id, date_created, id, live_mode, type, user_id e data.
• Header: Inclui a assinatura secreta x-signature, que permite validar a autenticidade da notificação.

A seguir, são apresentados exemplos das notificações para cada tópico.

plain
POST /?data.id=123456789&type=mp-connect HTTP/1.1
Host: test-optional-nots.requestcatcher.com
Accept: */*
Accept-Encoding: *
Connection: keep-alive
Content-Type: application/json
User-Agent: restclient-node/5.1.10
X-Request-Id: 4ed4fa2b-0b31-42ec-a62f-ad793c486c59
X-Rest-Pool-Name: /services/webhooks.js
X-Retry: 0
X-Signature: ts=1781009491,v1=654866c48793d9f716f255f8a8e6cb162f643d93b29391daa6ac7ce78cf0ce81
X-Socket-Timeout: 22000
{"action":"application.authorized","api_version":"v1","data":{"id":"123456789"},"date_created":"2026-06-12T13:14:01.351Z","id":100000000000,"live_mode":true,"type":"mp-connect","user_id":123456789}

A partir da notificação recebida, você poderá validar a autenticidade de sua origem por meio da chave secreta. Essa chave será enviada no header x-signature, com o seguinte formato:

plain
ts=1742505638683,v1=ced36ab6d33566bb1e16c125819b8d840d6b8ef136b0b9127c76064466f5229b

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

Siga uma das abordagens abaixo para validar a autenticidade da notificação.

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

Ações necessárias após receber a notificação

Quando você recebe uma notificação na sua plataforma, o Mercado Pago espera uma resposta para validar que o recebimento foi correto. Para isso, retorne um HTTP STATUS 200 ou 201 dentro de 22 segundos após o recebimento.

Recomendamos que você primeiro responda com um 200 ou 201, e depois processe a notificação no servidor, para evitar notificações duplicadas.

Se essa resposta não for enviada, o sistema realizará novas tentativas de envio a cada 15 minutos. Após as primeiras falhas, o intervalo se amplia progressivamente, mas as entregas continuam até que a notificação seja confirmada.

Além disso, tenha em mente:

• Ao receber um alerta de fraude, você deve reembolsar o pagamento sem entregar o pedido realizando uma chamada à API de Reembolsos.
• Para a gestão de contestações, consulte a documentação.