Configurar um webhook no Mercado Pago consiste em cadastrar uma URL no painel Suas integrações, definir quais eventos devem gerar notificações (pagamentos, reembolsos, chargebacks etc.) e criar um endpoint capaz de receber requisições HTTP POST. Dessa forma, as notificações são enviadas automaticamente ao seu servidor, sem necessidade de consultas recorrentes à API.
Neste artigo, você verá como configurar webhooks, preparar o endpoint, validar notificações com HMAC e identificar os erros mais comuns antes de colocá-los em produção.
O que é um webhook e por que ele importa na integração com o Mercado Pago
Um webhook é uma forma de comunicação entre sistemas em que o servidor de origem envia uma notificação automática via HTTP POST sempre que um evento específico ocorre. Isso contrasta com o modelo de polling, em que o seu servidor precisaria consultar a API do Mercado Pago de tempos em tempos para verificar se algo mudou.
No contexto do Mercado Pago, os webhooks cobrem eventos como aprovação de pagamentos, reembolsos, disputas e atualizações de orders. Cada vez que um desses eventos acontece, o Mercado Pago envia uma requisição ao endpoint cadastrado com os dados do evento em formato JSON.
Esse modelo reduz a carga no servidor, elimina consultas desnecessárias e garante que os dados da integração fiquem atualizados em tempo real. Para quem gerencia volumes altos de transações, a diferença entre polling e webhook pode representar uma queda relevante no consumo de recursos.
Como configurar webhook no Mercado Pago pelo painel Suas integrações
O processo de configuração acontece dentro do painel de desenvolvimento do Mercado Pago. Antes de acessar o painel, é preciso ter alguns itens prontos do lado do servidor.
Pré-requisitos antes de começar
Para que a configuração funcione sem interrupções, os seguintes itens precisam estar prontos:
- Conta ativa no Mercado Pago com acesso ao painel de desenvolvedores
- Aplicação criada em Suas integrações (sem ela, não há onde cadastrar o webhook)
- Endpoint com HTTPS ativo e certificado SSL válido — o Mercado Pago não aceita URLs sem criptografia
- Credenciais de teste e de produção separadas, para validar a integração antes de ir ao ar
Com esses elementos em mãos, o cadastro no painel pode acontecer sem bloqueios.
Passo a passo para cadastrar a URL e selecionar eventos
O fluxo de configuração segue uma sequência direta dentro do painel:
- Acesse suas integrações no painel do Mercado Pago Developers
- Selecione a aplicação para a qual deseja ativar as notificações
- No menu lateral, clique em Webhooks e depois em Configurar notificações
- Escolha a aba Modo teste e insira a URL do endpoint de desenvolvimento
- Repita o processo na aba Modo produção com a URL do ambiente real
- Selecione os eventos que devem disparar notificações — Pagamentos, Orders, Chargebacks, entre outros
- Clique em Salvar
Ao salvar, o painel gera uma chave secreta vinculada à aplicação. Essa chave será usada para validar a autenticidade de cada notificação recebida. Guarde-a em local seguro — ela não aparece novamente sem uma ação de renovação.
Caso a integração precise identificar múltiplas contas, o parâmetro ?client=nome_do_vendedor pode ser adicionado ao final da URL cadastrada.
Como simular o recebimento de notificações
O painel de Suas integrações oferece uma função de simulação que dispensa a necessidade de fazer um pagamento real para testar o fluxo. Para usá-la, basta selecionar a URL configurada, escolher o tipo de evento (por exemplo, Pagamentos), informar um Data ID de teste e clicar em Enviar teste.
O servidor receberá uma requisição POST com um corpo JSON contendo campos como type (tipo do evento), data.id (identificador do recurso) e date_created. A resposta esperada do endpoint é um status HTTP 200 ou 201 — qualquer outro código indica que algo no servidor precisa de ajuste antes de ir a produção.
Como preparar o endpoint do servidor para receber webhooks
A configuração no painel é apenas metade do trabalho. O endpoint do servidor precisa estar preparado para receber, responder e processar as notificações de forma adequada.
A primeira responsabilidade do endpoint é responder com status 200 ou 201 dentro do tempo limite aceito pelo Mercado Pago. Se a resposta demorar além desse threshold, a notificação é considerada falha e um reenvio é agendado. Por isso, o processamento da lógica de negócio — como atualizar o banco de dados ou liberar um pedido — deve acontecer de forma assíncrona, em segundo plano, enquanto o endpoint já retornou o status de sucesso.
O segundo ponto crítico é a idempotência. O Mercado Pago reenvia notificações em intervalos crescentes quando não recebe uma resposta 2xx. Isso significa que o mesmo evento pode chegar mais de uma vez ao endpoint. O servidor precisa identificar notificações duplicadas — usando o data.id como chave, por exemplo — e ignorá-las sem processar novamente.
Em linguagens como Node.js, Python e PHP, a lógica segue o mesmo padrão: receber o POST, extrair o type e o data.id do body, responder 200 de imediato e enfileirar o processamento para uma rotina assíncrona. A escolha da linguagem não altera a lógica esperada — o que muda é a forma de implementar a fila de processamento.
Validação de segurança: como verificar a origem do webhook no Mercado Pago
Receber uma notificação não é suficiente — é preciso confirmar que ela veio de fato do Mercado Pago antes de agir sobre ela. Para isso, cada requisição inclui o header x-signature com uma assinatura gerada a partir dos dados do evento.
O processo de validação funciona assim: o header x-signature contém dois valores — ts (timestamp da requisição) e v1 (o hash gerado). Com esses dados em mãos, o servidor monta um template no formato id:[data.id];request-id:[x-request-id];ts:[ts]; e gera um HMAC-SHA256 usando a chave secreta gerada no painel. Se o resultado coincidir com o valor de v1, a notificação é legítima.
Essa verificação previne que agentes mal-intencionados enviem notificações falsas ao endpoint, simulando pagamentos aprovados que nunca ocorreram. Sem essa etapa, uma integração pode liberar produtos ou serviços com base em dados fraudulentos.
A chave secreta não tem prazo de expiração definido, mas a renovação com regularidade é uma boa prática de segurança — em particular após mudanças na equipe ou suspeita de vazamento. A renovação pode ser feita dentro do próprio painel de Suas integrações.
Erros comuns ao configurar webhook no Mercado Pago e como resolver
Mesmo com a configuração seguindo o passo a passo, alguns problemas surgem com frequência no ambiente de desenvolvimento e, em alguns casos, chegam até a produção. Conhecer esses cenários com antecedência poupa horas de depuração.
Os erros mais frequentes incluem:
- URL sem HTTPS: o Mercado Pago rejeita endpoints sem certificado SSL válido. URLs HTTP ou com certificados autoassinados não são aceitas no cadastro
- Timeout na resposta: quando o servidor demora para responder, a notificação é marcada como falha e reenviada. O endpoint deve retornar 200 antes de iniciar qualquer processamento pesado
- Falta de idempotência: sem verificação de duplicatas, o mesmo evento pode ser processado mais de uma vez — gerando cobranças duplicadas, liberações indevidas ou inconsistências no banco de dados
- Ignorar a validação HMAC: aceitar qualquer requisição POST sem verificar o x-signature abre brecha para notificações falsas e possíveis fraudes
- Confusão entre credenciais de teste e produção: usar a chave de produção no ambiente de teste — ou o inverso — faz com que as notificações não cheguem no ambiente esperado, dificultando o diagnóstico
Manter logs detalhados de cada notificação recebida — incluindo headers, body e o status de resposta enviado — é a forma mais eficiente de depurar qualquer um desses cenários. Com os logs em mãos, fica possível reproduzir o problema e identificar em qual etapa a integração falhou.
Perguntas frequentes sobre webhook no Mercado Pago
Qual a diferença entre webhook e IPN no Mercado Pago?
O IPN (Instant Payment Notification) é o sistema legado de notificações do Mercado Pago. Os webhooks são o método atual e indicado para novas integrações, com suporte a mais tipos de eventos e validação por assinatura HMAC. Para quem ainda usa IPN, a migração para webhooks é o caminho recomendado.
O que acontece se meu servidor estiver fora do ar quando o webhook for enviado?
O Mercado Pago tenta reenviar a notificação em intervalos crescentes. Como os reenvios podem gerar duplicatas, o endpoint precisa ser idempotente para lidar com esse cenário sem processar o mesmo evento duas vezes. Caso as tentativas se esgotem, o status do pagamento pode ser consultado via API como alternativa.
Posso configurar webhooks para mais de uma aplicação no Mercado Pago?
Cada aplicação criada em Suas integrações pode ter sua própria configuração de webhook, com URLs e eventos distintos. O parâmetro ?client=nome_do_vendedor na URL ajuda a identificar qual conta originou cada notificação quando há múltiplas contas envolvidas.
É possível testar webhooks sem fazer um pagamento real?
O painel Suas integrações oferece a função de simulação de notificações, que dispensa pagamentos reais. Também é possível usar credenciais de teste com a URL de modo teste para simular o fluxo completo. Ferramentas externas de inspeção de requisições HTTP podem complementar a depuração ao mostrar exatamente o que o servidor está recebendo.
Quem quer colocar a integração no ar com segurança pode começar pelo painel Suas integrações do Mercado Pago Developers, que reúne credenciais, documentação e a função de simulação de webhooks num só lugar. Criar a aplicação por lá e testar o fluxo antes de ir à produção reduz bastante o risco de problemas inesperados no ambiente real.
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