Configurar notificações

A seguir, apresentamos um passo a passo para receber notificações de pagamento em integrações com Checkout Transparente. Uma vez configuradas, as notificações Webhook serão enviadas sempre que ocorrer qualquer atualização sobre o tópico reportado, incluindo criação e atualização de orders e processamento de transações.

1. Acesse Integrações e selecione a aplicação integrada com Checkout Transparente para a qual deseja ativar as notificações.

2. No menu lateral, selecione Configuração de Webhooks.

3. No switch Teste / Produção da parte superior, selecione Teste e insira a URL HTTPS para receber notificações de teste. Se quiser configurar notificações de produção, selecione Produção e insira a URL HTTPS de produção.

4. Selecione o evento Order (Mercado Pago) para receber notificações, que serão enviadas em formato JSON através de um HTTPS POST para a URL configurada para o ambiente correspondente.

5. Por fim, clique em Salvar. Isso gerará uma assinatura secreta exclusiva para a aplicação, que permitirá validar a autenticidade das notificações recebidas e confirmar que foram enviadas pelo Mercado Pago. A assinatura não tem prazo de validade e sua renovação periódica não é obrigatória, embora seja recomendada. Para renová-la, clique em Redefinir assinatura secreta.

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 seus Webhooks, clique em Simular notificação.
2. Na tela de simulação, selecione a URL que será testada.
3. Em seguida, selecione o tipo de evento e insira a identificação que será enviada no corpo da notificação (Data ID).

4. Por fim, clique em Enviar teste para verificar a solicitação, a resposta fornecida pelo servidor e a descrição do evento. Você receberá uma resposta conforme o exemplo abaixo, que representa o body da notificação recebida em seu servidor.

json
{
  "action": "order.processed",
  "api_version": "v1",
  "application_id": "7255333517291496",
  "data": {
    "currency_id": "ARS",
    "external_reference": "ext_ref_1234",
    "id": "ORD01M28P44G5FG8RJPM579EH56FV",
    "items": [
      {
        "external_code": "6754960",
        "quantity": 1
      }
    ],
    "status": "processed",
    "status_detail": "accredited",
    "total_amount": "200.00",
    "total_paid_amount": "200.00",
    "transactions": {
      "payments": [
        {
          "amount": "200.00",
          "id": "PAY01M28P44GDSD4JYTSK5SYZT6BH",
          "paid_amount": "200.00",
          "payment_method": {
            "id": "master",
            "installments": 1,
            "type": "credit_card"
          },
          "reference": {
            "id": "000fkonfh0"
          },
          "status": "processed",
          "status_detail": "accredited"
        }
      ]
    },
    "type": "online",
    "version": 1
  },
  "date_created": "2026-09-11T16:52:02.736053815Z",
  "live_mode": true,
  "type": "order",
  "user_id": "11111111"
}

Para consultar o funcionamento das notificações, abra a aplicação e, em Início, selecione a aba Webhooks. Utilize o switch Teste / Produção para consultar as notificações do ambiente selecionado.

Nessa tela, você pode filtrar os envios, consultar data, status da entrega, ação, evento e ID do recurso, e revisar as métricas de entrega e tempo de resposta. Em Teste, os dados são atualizados em tempo real.

Para consultar os dados do envio e o corpo da notificação, selecione uma notificação da tabela para abrir os detalhes.

Para reenviar uma ou mais notificações, selecione-as na tabela e clique em Reenviar notificações.

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=ORD01M28P44G5FG8RJPM579EH56FV e type=order.
• Body: O corpo da notificação contém informações detalhadas sobre o evento e a order, incluindo action, data.status, data.status_detail e data.transactions.payments.
• Header: O cabeçalho contém metadados importantes, incluindo a assinatura secreta da notificação x-signature.

plain
POST /test?data.id=ORD01M28P44G5FG8RJPM579EH56FV&type=order HTTP/1.1
Host: prueba.requestcatcher.com
Accept: */*
Accept-Encoding: *
Connection: keep-alive
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":"7255333517291496","data":{"currency_id":"ARS","external_reference":"ext_ref_1234","id":"ORD01M28P44G5FG8RJPM579EH56FV","items":[{"external_code":"6754960","quantity":1}],"status":"processed","status_detail":"accredited","total_amount":"200.00","total_paid_amount":"200.00","transactions":{"payments":[{"amount":"200.00","id":"PAY01M28P44GDSD4JYTSK5SYZT6BH","paid_amount":"200.00","payment_method":{"id":"master","installments":1,"type":"credit_card"},"reference":{"id":"000fkonfh0"},"status":"processed","status_detail":"accredited"}]},"type":"online","version":1},"date_created":"2026-09-11T16:52:02.736053815Z","live_mode":true,"type":"order","user_id":"11111111"}

A partir da notificação Webhook recebida, você poderá validar a autenticidade da 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, que será similar ao exemplo abaixo.

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 a sua aplicação em Configuração de Webhooks.

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

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 a terceira tentativa, o prazo será prorrogado, mas os envios continuarão acontecendo.

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.

Com essa informação, você poderá realizar as atualizações necessárias em sua plataforma, como atualizar um pagamento aprovado.