Para configurar webhooks do Mercado Pago, o caminho começa no painel Suas integrações: selecione a aplicação desejada, acesse Webhooks > Configurar notificações, cadastre uma URL HTTPS válida, escolha os eventos que deseja monitorar e salve. Com isso, seu servidor passa a receber notificações automáticas via HTTP POST cada vez que um evento ocorre — sem precisar consultar a API de forma repetida para verificar o status de um pagamento.
Ao longo deste artigo, você vai encontrar os pré-requisitos técnicos para começar, o passo a passo detalhado de cada etapa no painel, como usar a função de simulação antes de ir para produção, como validar a autenticidade das notificações com a assinatura secreta e, sobretudo, como diagnosticar os erros mais comuns que a documentação oficial não aprofunda.
O que são webhooks e por que usá-los na integração com o Mercado Pago
Um webhook é uma notificação automática que um sistema envia para outro quando um evento acontece. Na prática, funciona como um HTTP POST disparado pelo Mercado Pago para a URL do seu servidor no momento em que, por exemplo, um pagamento é aprovado ou uma cobrança é contestada.
A alternativa seria o polling: seu servidor consultaria a API do Mercado Pago de tempos em tempos para verificar se algo mudou. Isso consome recursos do servidor, aumenta a latência e eleva o risco de perder eventos entre uma consulta e outra. Com webhooks, os dados chegam no instante em que o evento ocorre.
Para quem integra pagamentos, isso tem impacto direto na experiência de quem compra. O status do pedido é atualizado em tempo real, sem depender de uma verificação agendada. O resultado é uma integração mais eficiente, com menos chamadas à API e maior confiabilidade no fluxo de confirmação.
Pré-requisitos antes de configurar webhooks do Mercado Pago
Antes de acessar o painel e começar a configuração, alguns itens precisam estar prontos. Pular essa etapa é uma das causas mais comuns de falhas silenciosas na integração.
O que você precisa ter em mãos:
- Conta de desenvolvedor ativa no Mercado Pago, com pelo menos uma aplicação criada no painel Suas integrações
- URL HTTPS com certificado SSL válido e acessível pela internet — o Mercado Pago não aceita URLs com HTTP simples nem certificados autoassinados
- Servidor configurado para receber requisições POST e retornar um status HTTP 200 ou 201 dentro do tempo limite
- Ambiente de teste funcional — para quem desenvolve localmente, ferramentas como ngrok ou Cloudflare Tunnel geram URLs HTTPS temporárias que expõem o servidor local à internet, o que permite testar sem precisar de um servidor em produção
Esse último ponto é algo que os competidores raramente mencionam. Testar webhooks em ambiente local sem uma ferramenta de tunelamento é inviável, já que o Mercado Pago precisa alcançar sua URL pela internet. Com o ngrok, por exemplo, você obtém uma URL pública HTTPS em segundos, apontando para o seu localhost.
Passo a passo para configurar webhooks no painel do Mercado Pago
O processo de configuração acontece no painel Suas integrações do Mercado Pago. A seguir, cada etapa com detalhes que vão além do que a documentação padrão apresenta.
Como cadastrar as URLs de teste e produção
O ponto de entrada é sempre o painel Suas integrações. Siga esta sequência:
- Acesse Suas integrações e selecione a aplicação que receberá as notificações
- No menu lateral, clique em Webhooks e depois em Configurar notificações
- Na aba Modo de teste, insira a URL que receberá notificações durante os testes (use suas credenciais de teste aqui)
- Na aba Modo produtivo, insira a URL que receberá notificações reais em produção
Manter as duas URLs separadas é uma boa prática que evita um erro comum: disparar notificações de teste para o servidor de produção ou vice-versa. Se você gerencia mais de uma conta ou aplicação, o parâmetro ?cliente=(nome) ao final da URL ajuda a identificar a origem de cada notificação no seu servidor.
Como selecionar os eventos de notificação
O Mercado Pago oferece diferentes tipos de eventos. Cada um atende a um cenário específico, e escolher apenas os que fazem sentido para a sua integração reduz o volume de notificações desnecessárias.
- payment: notifica sobre criação, atualização ou cancelamento de pagamentos — o evento mais usado em e-commerce e checkouts online
- merchant_order: agrupa pagamentos relacionados a uma ordem de compra, útil quando uma compra pode ter múltiplos pagamentos associados
- chargebacks: avisa quando uma cobrança é contestada pelo titular do cartão, permitindo acionar o fluxo de disputa com agilidade
- point_integration_wh: voltado para integrações com o Mercado Pago Point, o dispositivo de pagamento presencial — indicado para lojas físicas que processam cartões no balcão
A documentação oficial lista esses eventos, mas não explica quando usar cada um. Quem desenvolve um e-commerce com checkout online, por exemplo, precisa do evento payment. Já quem opera um PDV físico com leitora de cartão vai depender do point_integration_wh para saber quando uma transação foi concluída no dispositivo.
Como salvar e gerar a chave secreta
Após cadastrar as URLs e selecionar os eventos, clique em Salvar configuração. Nesse momento, o Mercado Pago gera uma chave secreta exclusiva para a aplicação.
Essa chave aparece no painel e é usada para validar a autenticidade de cada notificação recebida. Guarde-a em um local seguro — ela não aparece novamente da mesma forma após sair da tela. A chave não tem prazo de validade, mas a renovação com regularidade é uma boa prática de segurança. Para renovar, basta clicar em Restabelecer no painel.
Como testar e simular webhooks do Mercado Pago antes de ir para produção
Após salvar a configuração, o painel libera a função Simular. Com ela, é possível disparar uma notificação de teste sem precisar realizar uma transação real.
Para usar, clique em Simular, selecione a URL de destino, o tipo de evento e um ID de teste. O Mercado Pago envia uma requisição POST para a URL escolhida com um body JSON que inclui campos como action, data.id, type e live_mode: false. O campo live_mode: false confirma que se trata de uma notificação de ambiente de teste — se aparecer true, algo está errado na configuração das URLs.
O que observar durante a simulação é se o seu servidor responde com status 200 e se o corpo da notificação chega com os campos esperados. Muitas integrações chegam à produção com falhas silenciosas justamente porque essa etapa foi pulada.
Validação de segurança e erros comuns ao configurar webhooks
Receber a notificação é só parte do processo. Validar que ela veio do Mercado Pago e saber diagnosticar falhas são etapas que definem uma integração robusta.
Como validar a origem da notificação com a assinatura secreta
Cada notificação enviada pelo Mercado Pago inclui o header x-signature, que contém dois valores: ts (timestamp do envio) e v1 (hash HMAC-SHA256 gerado com a chave secreta).
Para validar a autenticidade, seu servidor precisa:
- Extrair os valores de ts e v1 do header x-signature
- Montar a string de validação no formato id:[data.id];request-id:[x-request-id];ts:[ts];
- Gerar um hash HMAC-SHA256 dessa string usando a chave secreta gerada no painel
- Comparar o hash gerado com o valor de v1 recebido no header
Se os valores coincidirem, a notificação é legítima. Se não coincidirem, descarte a requisição — pode ser uma tentativa de injetar dados falsos no seu sistema. Essa validação é o que separa uma integração segura de uma vulnerável a fraudes.
Erros frequentes e como resolver cada um
A maioria dos problemas com webhooks aparece depois da configuração, quando as notificações não chegam ou chegam com falha. Os erros abaixo são os que mais aparecem na prática — e que a documentação oficial trata de forma superficial:
- URL retornando 301 ou 302 (redirecionamento): webhooks não seguem redirects. Se sua URL redireciona de HTTP para HTTPS, por exemplo, o Mercado Pago vai receber o redirect e considerar a entrega como falha. A solução é cadastrar a URL final, já com HTTPS, sem redirecionamentos
- Certificado SSL inválido ou autoassinado: o Mercado Pago valida o certificado antes de enviar a notificação. Certificados autoassinados ou expirados causam falha na conexão. Use um certificado emitido por uma autoridade reconhecida — Let's Encrypt, por exemplo, é gratuito e amplamente aceito
- Timeout do servidor (resposta acima de 10 segundos): se o servidor demorar mais de 10 segundos para responder, o Mercado Pago considera a entrega como falha. Se o processamento da notificação for pesado, a solução é retornar o status 200 imediatamente e processar os dados de forma assíncrona em segundo plano
- Não retornar status 2xx: o Mercado Pago interpreta qualquer resposta fora do intervalo 2xx como falha e agenda retentativas com intervalos crescentes. Após várias tentativas sem sucesso, a notificação pode ser descartada
- Credenciais misturadas: usar credenciais de produção para testar a URL de teste (ou o contrário) é um erro comum que gera comportamentos inesperados. Sempre confirme qual par de credenciais está ativo no ambiente que está testando
Com esses pontos resolvidos, a integração passa a funcionar de forma estável tanto em testes quanto em produção.
Perguntas frequentes sobre webhooks do Mercado Pago
O Mercado Pago reenvia notificações se o servidor não responder?
Sim. Quando o servidor não retorna um status 2xx, o Mercado Pago agenda retentativas com intervalos crescentes. Após várias tentativas sem sucesso, a notificação pode ser descartada. Por isso, retornar o status correto é fundamental para garantir que nenhum evento se perca.
Posso configurar webhooks para mais de uma aplicação ao mesmo tempo?
Cada aplicação criada no painel Suas integrações tem sua própria configuração de webhooks, com URLs e eventos independentes. É possível usar URLs diferentes para cada aplicação e, quando necessário, o parâmetro ?cliente=(nome) na URL ajuda a identificar de qual aplicação veio cada notificação no servidor.
Qual a diferença entre configurar webhooks pelo painel e durante a criação do pagamento?
A configuração pelo painel vale para todos os pagamentos da aplicação de forma geral. Já a configuração feita durante a criação de um pagamento específico tem prioridade sobre a do painel e vale apenas para aquela transação. Essa segunda opção é útil em cenários onde a URL ou os eventos precisam variar por transação — como marketplaces com múltiplos vendedores.
Preciso de HTTPS para receber webhooks do Mercado Pago?
Sim. O Mercado Pago exige uma URL com HTTPS e certificado SSL válido. URLs com HTTP simples ou certificados auto-assinados não são aceitas. Para testes em ambiente local, ferramentas de tunelamento como ngrok ou Cloudflare Tunnel geram URLs HTTPS temporárias que funcionam bem nessa etapa.
Com o passo a passo aplicado e os erros mais comuns mapeados, você já tem o que precisa para começar. O próximo passo é acessar o painel Suas integrações do Mercado Pago, selecionar sua aplicação e colocar a configuração em prática, a documentação oficial para desenvolvedores pode complementar os detalhes específicos de cada tipo de evento conforme sua integração avança.
Aplicam-se restrições. Consulte mais informações sobre produtos, serviços e termos de uso em: https://www.mercadopago.com.br/ajuda/termos-e-condicoes_299
