// artigo · pagamentos
Webhook do Mercado Pago: confirmar o pagamento automaticamente
O webhook é a peça que libera o pedido sozinho quando o pagamento cai — sem depender de o cliente ficar na tela. É também onde mais gente tropeça. Veja o fluxo certo, a validação segura e por que às vezes ele não chega.
O problema: perguntar "já pagou?" não funciona
Quando alguém paga um PIX ou um cartão, a aprovação pode levar segundos — ou acontecer depois que o cliente já fechou a aba. Se o seu sistema depende de o cliente continuar na tela para confirmar, você vai perder pedidos pagos e liberar pedidos que não foram.
A solução não é ficar consultando a API de tempos em tempos ("já pagou? já pagou?"). É deixar o Mercado Pago avisar você no exato momento em que o status muda. Esse aviso é o webhook.
O que é um webhook (em um minuto)
Um webhook é uma notificação automática: em vez de o seu sistema perguntar, o Mercado Pago faz uma requisição HTTP para uma URL sua assim que um evento acontece — por exemplo, um pagamento aprovado.
Na prática, você cadastra uma URL do tipo https://seusite.com/webhook/mercadopago e passa a receber ali um aviso cada vez que um pagamento muda de estado: aprovado, recusado, estornado, em processo.
O fluxo certo, passo a passo
- O cliente paga (PIX ou cartão) no seu checkout.
- O Mercado Pago chama a sua URL de webhook, enviando o ID do pagamento e o tipo de evento — nada mais.
- Seu sistema consulta a API do Mercado Pago com aquele ID para descobrir o status real e confiável do pagamento.
- Se aprovado, o pedido é liberado: baixa no estoque, e-mail ao cliente, nota, o que for.
- Seu endpoint responde 200 rapidamente, para o Mercado Pago saber que o aviso foi recebido.
Repare no passo 3: a notificação não traz o valor nem o status final de forma confiável — ela traz o ID. Quem dá a palavra final é a consulta à API. Liberar pedido pelo corpo do aviso é um erro clássico (e perigoso).
Validar a notificação (não confie cegamente)
Qualquer um pode tentar chamar a sua URL de webhook. Por isso, duas verificações são obrigatórias:
- Assinatura (x-signature): o Mercado Pago assina cada notificação. Seu sistema recalcula a assinatura com a sua chave secreta e compara — se não bater, descarta.
- Consulta à fonte: sempre buscar o pagamento na API pelo ID antes de liberar qualquer coisa. O status que vale é o que a API responde, não o que chegou no aviso.
Sem isso, um atacante poderia forjar uma notificação de "pagamento aprovado" e liberar um pedido sem ter pago.
Idempotência: o mesmo aviso pode chegar duas vezes
O Mercado Pago reenvia a notificação se o seu endpoint não responder 200 a tempo. Resultado: a mesma notificação de pagamento pode chegar mais de uma vez.
Seu processamento precisa ser idempotente: processar o mesmo pagamento duas vezes não pode liberar o pedido duas vezes, nem dar baixa dobrada no estoque, nem enviar dois e-mails. O caminho usual é registrar o ID do pagamento já processado e ignorar repetições.
Por que o webhook não chega? Erros comuns
Se o aviso não aparece, quase sempre é um destes:
- URL não é HTTPS público: em ambiente local (localhost) o Mercado Pago não alcança a sua máquina. Para testar, use um túnel (ex.: ngrok) ou um ambiente publicado.
- Endpoint demora para responder: se o seu código processa tudo antes de responder, pode estourar o tempo. Responda 200 rápido e processe o resto em seguida (ou em fila).
- Erro 500 no seu código: uma exceção não tratada faz o Mercado Pago entender que falhou — e reenviar, às vezes em loop.
- URL de notificação não configurada no painel ou não enviada na criação do pagamento.
Regra de ouro: responda 200 primeiro, processe depois. Um endpoint que faz muito trabalho antes de responder é a causa nº 1 de webhook "perdido".
Como a Mantis faz
A confirmação por webhook é exatamente a parte que a gente cuida numa integração de pagamentos: endpoint que responde rápido, validação de assinatura, consulta à API, idempotência e testes de ponta a ponta com os casos reais — aprovado, recusado, estorno e reenvio.
Vale tanto para o Checkout Pro quanto para o Transparente: a confirmação é a mesma nos dois. Tudo no sistema que você já tem, sem migrar de plataforma.
Perguntas frequentes
O que é o webhook do Mercado Pago?
É uma notificação automática que o Mercado Pago envia ao seu sistema sempre que o status de um pagamento muda (aprovado, recusado, estornado). Em vez de o seu sistema perguntar "já pagou?", ele é avisado na hora.
Preciso validar a notificação do webhook?
Sim. A notificação só traz o ID do pagamento; o seu sistema deve consultar a API com esse ID para confirmar o status real e validar a assinatura (x-signature). Nunca libere o pedido apenas pelo corpo da requisição.
Por que o webhook do Mercado Pago não chega?
As causas mais comuns são: URL não ser HTTPS público e acessível, o servidor demorar para responder (precisa responder 200 rápido), erros 500 no seu código, ou a URL de notificação não estar configurada. Em falha, o Mercado Pago reenvia — então o endpoint precisa ser idempotente.
O Mercado Pago reenvia a mesma notificação?
Sim. Se o endpoint não responder 200 a tempo, a notificação é reenviada e pode chegar mais de uma vez. Por isso o processamento deve ser idempotente: processar o mesmo pagamento duas vezes não pode liberar o pedido duas vezes.