Os webhooks do Mercado Pago funcionam como notificações automáticas enviadas ao seu servidor sempre que um evento relevante acontece — como a aprovação de um pagamento ou a compensação de um boleto. A configuração envolve dois passos principais: registrar uma URL de notificação no painel de desenvolvedor e criar um endpoint no seu servidor preparado para receber requisições POST com dados em formato JSON.
Ao longo deste artigo, você vai encontrar a diferença entre webhooks e o modelo de polling, o passo a passo para configurar a integração, como validar a autenticidade das notificações com segurança, exemplos concretos de automação para e-commerce, ERP e e-mails transacionais, além de um guia para testar o fluxo e resolver os problemas mais comuns — incluindo o que fazer quando a notificação simplesmente não chega.
Webhooks do Mercado Pago: o que são e por que substituem o polling
Antes de configurar qualquer coisa, vale entender o mecanismo por trás dos webhooks e por que essa abordagem pode ser mais eficiente do que consultar a API de forma repetida.
Como funciona o modelo push dos webhooks
O modelo de polling funciona como um sistema pull: o seu servidor faz requisições à API em intervalos regulares para verificar se alguma coisa mudou. Isso consome recursos do servidor, gera tráfego desnecessário e pode introduzir atrasos entre o evento real e a resposta do seu sistema.
Os webhooks invertem essa lógica com o modelo push: em vez de o seu sistema perguntar, o Mercado Pago avisa. Quando um evento ocorre, o sistema envia uma requisição HTTP POST com os dados relevantes diretamente para a URL que você registrou. O resultado é uma entrega de informação em tempo real com muito menos carga no servidor.
Eventos que geram notificações no Mercado Pago
Nem todo evento dispara uma notificação automaticamente — você escolhe quais acompanhar. Os principais eventos configuráveis incluem:
- Pagamento aprovado
- Pagamento recusado
- Estorno ou reembolso solicitado
- Compensação de boleto bancário
- Atualização de assinatura recorrente
- Criação ou atualização de order
Cada evento pode ser ativado ou desativado de forma independente no painel do desenvolvedor. Isso dá controle sobre o volume de notificações recebidas e evita que o endpoint processe eventos irrelevantes para o seu negócio.
Passo a passo para configurar webhooks do Mercado Pago
Com o conceito claro, o próximo passo é colocar a configuração em prática. O processo envolve preparar seu servidor, registrar a URL no painel de desenvolvedor e programar o endpoint que vai processar os dados recebidos.
Requisitos técnicos antes de começar
Antes de acessar o painel, verifique se o seu ambiente atende aos pré-requisitos básicos:
- Servidor com HTTPS ativo (certificado SSL/TLS válido)
- Endpoint público e acessível pela internet
- Capacidade de receber requisições POST e ler o body em JSON
- Retorno de status HTTP 200 após processar cada notificação
- Conta no Mercado Pago com ao menos uma aplicação criada em “Suas integrações”
Sem HTTPS, o Mercado Pago não envia notificações ao endpoint. Esse requisito existe para proteger os dados em trânsito e não tem exceção.
Como registrar a URL de notificação no painel
O registro da URL segue uma sequência direta dentro do painel de desenvolvedor:
- Acesse “Suas integrações” e selecione a aplicação desejada
- No menu lateral, clique em Webhooks > Configurar notificações
- Insira a URL de modo teste (para o ambiente Sandbox)
- Insira a URL de modo produção (para transações reais)
- Selecione os eventos que deseja monitorar
- Salve a configuração
Ao salvar, o painel gera uma chave secreta vinculada àquela aplicação. Essa chave é usada para validar a autenticidade de cada notificação recebida — guarde-a em local seguro e nunca a exponha no código-fonte público.
Como criar o endpoint que recebe as notificações
O endpoint precisa seguir uma lógica específica para funcionar com segurança. Quando uma notificação chega, o fluxo esperado é:
- Receber a requisição POST e ler o body JSON
- Extrair o tipo de evento e o ID do recurso
- Validar a assinatura do header (detalhado na próxima seção)
- Consultar a API do Mercado Pago com o ID recebido para obter os dados completos
- Retornar HTTP 200 para confirmar o recebimento
Um ponto que gera confusão em quem começa: o payload do webhook não traz todos os dados da transação. Por segurança, ele contém apenas o tipo de evento e o ID do recurso. Os detalhes completos — valor, método de pagamento, dados de quem pagou — chegam via consulta à API com aquele ID. As SDKs oficiais do Mercado Pago para Python, Node.js, Java e PHP facilitam essa etapa de consulta.
Como validar a segurança das notificações recebidas
Receber notificações é só uma parte do processo. Garantir que cada requisição vem de uma fonte legítima é o que protege seu sistema contra tentativas de manipulação.
Verificação da assinatura no header x-signature
Cada notificação enviada pelo Mercado Pago inclui um header x-signature. Esse header carrega uma assinatura gerada com base nos dados da requisição e na chave secreta da sua aplicação. O fluxo de validação segue três etapas:
- Extrair o valor do header x-signature da requisição recebida
- Gerar um hash usando a chave secreta e os dados do body
- Comparar o hash gerado com a assinatura recebida
Se os valores não coincidirem, a notificação deve ser descartada sem processamento. Esse mecanismo impede que terceiros enviem requisições falsas ao seu endpoint fingindo ser o Mercado Pago.
Boas práticas de registro e monitoramento
Além da validação de assinatura, algumas práticas tornam a integração mais robusta ao longo do tempo:
- Mantenha logs de todas as notificações recebidas, com timestamp, tipo de evento, ID do recurso e resposta do sistema
- Implemente idempotência no processamento: se a mesma notificação chegar duas vezes (o que pode acontecer por retentativas), o sistema não deve executar a ação duplicada
- Monitore falhas com alertas quando o endpoint retornar erro ou quando a taxa de notificações cair abaixo do esperado
Logs detalhados são o principal aliado na hora de depurar problemas. Sem eles, identificar por que um pedido não foi atualizado ou por que um e-mail não foi enviado pode levar muito mais tempo do que o necessário.
Exemplos de automação com webhooks na prática
A configuração técnica ganha sentido quando conectada a cenários reais de negócio. Veja como webhooks podem automatizar processos que consomem tempo e atenção manual.
Atualização de status de pedido em e-commerce
O fluxo de uma venda online com webhooks funciona assim: o cliente conclui o pagamento na loja, o Mercado Pago processa a transação e dispara uma notificação ao endpoint registrado com o evento de aprovação. O servidor recebe o payload, extrai o ID do pagamento e faz uma consulta à API para confirmar o status. Com a confirmação, o sistema atualiza o pedido no banco de dados — de “pendente” para “pago” — e libera o processo de separação e envio do produto.
Esse fluxo elimina a necessidade de qualquer verificação manual. A atualização acontece em segundos após a aprovação, sem que ninguém precise checar o painel ou consultar o extrato. Para negócios com alto volume de pedidos, essa diferença tem impacto direto na capacidade operacional.
Disparo de e-mails e sincronização com ERP ou CRM
Os mesmos eventos que atualizam pedidos podem acionar outras automações em paralelo. Alguns exemplos práticos:
- E-mail de confirmação enviado ao cliente logo após a aprovação do pagamento
- Notificação de reembolso disparada quando um estorno é registrado
- Registro contábil gerado no ERP com os dados da transação aprovada
- Fatura criada de forma automática no sistema financeiro
- Cadastro de cliente atualizado no CRM com o histórico de compra
Todas essas ações podem ser encadeadas num mesmo fluxo de trabalho. Quando o evento de pagamento aprovado chega, o sistema pode atualizar o pedido, enviar o e-mail e registrar a transação no ERP em sequência — sem intervenção humana em nenhuma etapa.
Como testar webhooks e resolver problemas comuns
Antes de colocar a integração em produção, testar o fluxo completo evita surpresas. E quando algo não funciona como esperado, saber onde procurar o problema faz toda a diferença.
Testes no ambiente Sandbox e ferramentas de apoio
O Mercado Pago disponibiliza um ambiente Sandbox para simular eventos com credenciais de teste, sem movimentar dinheiro real. No painel de webhooks, a funcionalidade “Simular” permite enviar uma notificação de teste para a URL cadastrada e verificar se o endpoint a recebe com sucesso.
Para quem desenvolve localmente, duas ferramentas são bastante úteis:
- Ngrok: cria uma URL pública temporária que redireciona para o servidor local, tornando o endpoint acessível pela internet durante o desenvolvimento
- Postman: permite simular requisições POST com payloads personalizados e inspecionar a resposta do endpoint
Com essas ferramentas, é possível validar todo o fluxo — do recebimento da notificação à consulta à API — antes de apontar para produção.
Erros frequentes e o que fazer quando a notificação não chega
Este é um dos pontos que a documentação oficial cobre de forma superficial. Quando algo não funciona, os problemas costumam se encaixar em algumas categorias:
- Endpoint retornando 4xx ou 5xx: verificar se a URL está acessível publicamente, se o servidor está no ar e se o endpoint responde HTTP 200 após processar a requisição
- Falha na validação de assinatura: conferir se a chave secreta usada no código corresponde à gerada no painel para aquela aplicação
- Notificações duplicadas chegando: implementar idempotência usando o ID do evento como chave de controle
- Notificação que não chega de forma alguma: verificar se o evento está selecionado no painel, se a URL de produção ou teste está correta para o ambiente em uso, e se o servidor não bloqueia requisições externas por firewall ou regras de segurança
Quando o webhook falha e a notificação não chega, o Mercado Pago aplica uma política de retentativas automáticas: o sistema reenvia a notificação em intervalos crescentes quando não recebe HTTP 200. Como alternativa temporária, é possível consultar a API via GET com o ID do recurso para recuperar os dados de eventos que não foram notificados — mas essa consulta manual não substitui a correção do problema no endpoint.
Perguntas frequentes sobre webhooks do Mercado Pago
Qual a diferença entre webhooks e IPN no Mercado Pago?
O IPN (Instant Payment Notification) é um método mais antigo de notificação do Mercado Pago, com menos opções de configuração e sem suporte à validação por assinatura. Os webhooks são a versão atual e recomendada, com maior variedade de eventos configuráveis e mecanismo de segurança mais robusto. A documentação oficial do Mercado Pago incentiva a migração de integrações que ainda usam IPN para o modelo de webhooks.
O que acontece se meu servidor estiver fora do ar quando o webhook é enviado?
O Mercado Pago conta com uma política de retentativas automáticas. Quando o endpoint não retorna HTTP 200, o sistema reenvia a notificação em intervalos crescentes por um período determinado. Para eventos que passaram pela janela de retentativas sem sucesso, é possível consultar a API via GET usando o ID do recurso para recuperar os dados manualmente — uma solução de contingência enquanto o problema no servidor é resolvido.
É possível configurar webhooks para mais de uma aplicação?
Cada aplicação criada em “Suas integrações” tem sua própria configuração de webhooks, com URLs e eventos independentes. Para quem gerencia múltiplas contas de vendedores numa mesma URL, o parâmetro ?client=(nomedovendedor) ao final da URL ajuda a identificar de qual conta veio cada notificação. Essa flexibilidade permite separar ambientes ou negócios distintos sem conflito entre as integrações.
Os webhooks do Mercado Pago enviam todos os dados da transação?
O payload do webhook contém apenas o tipo de evento e o ID do recurso — não os dados completos da transação. Para obter informações como valor, método de pagamento e dados de quem pagou, é necessário fazer uma consulta à API do Mercado Pago usando o ID recebido. Essa abordagem protege informações sensíveis e evita que dados completos trafeguem sem necessidade a cada notificação.
Quem chega até aqui já tem o mapa completo para sair do zero e ter webhooks funcionando em produção. O próximo passo prático é acessar o painel de desenvolvedor do Mercado Pago, criar ou selecionar uma aplicação em “Suas integrações” e registrar a primeira URL de notificação. Com o ambiente Sandbox disponível para testes, dá para validar todo o fluxo antes de apontar para produção — e começar a automatizar os processos que hoje ainda dependem de verificação manual.
Consulte condições e tarifas em: