Configurar notificações de Perfis de Pagamento
Os webhooks de Perfis de Pagamento notificam sua aplicação em tempo real sempre que um perfil vinculado à sua integração sofrer uma mudança relevante. Em vez de consultar a API periodicamente, você recebe as atualizações no momento em que ocorrem via HTTP POST.
Dessa forma, é possível detectar quando um perfil atinge o status ready para liberar o fluxo de cobranças recorrentes, realizar as ações necessárias quando um método de pagamento vinculado a um perfil é desativado ou cancelado, e manter seu sistema sempre sincronizado com o estado real do perfil.
flowchart TD
A[Mudança no perfil] --> B{Verifica elegibilidade}
B -->|Não elegível| C[Evento descartado]
B -->|Elegível| D["POST {sua-url} com payload JSON"]
D --> E[Sua aplicação responde HTTP 200]
E --> F[Processa o evento de forma assíncrona]
Siga o passo a passo abaixo para configurar as notificações de Perfis de Pagamento.
- Acesse Integrações e selecione a aplicação para a qual deseja ativar as notificações.
-
No menu lateral, selecione Configuração de Webhooks.
-
No switch Teste / Produção da parte superior, selecione Teste e insira a
URL HTTPSpara receber notificações de teste. Se quiser configurar notificações de produção, selecione Produção e insira aURL HTTPSde produção. -
Selecione o evento Perfil de Pagamento (
payment_profile) para receber notificações de mudanças no perfil.
- 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 estejam configuradas corretamente, simule o recebimento seguindo o passo a passo abaixo.
- Após configurar a URL e o evento, clique em Salvar.
- Em seguida, clique em Simular notificação para verificar se a URL indicada está recebendo as notificações corretamente.
- Na tela de simulação, selecione a URL a ser testada.
- Escolha o tipo de evento Perfil de Pagamento e insira o ID do perfil que será enviado no corpo da notificação (
Data ID). - Por fim, clique em Enviar teste para verificar a solicitação, a resposta do servidor e a descrição do evento.
Para consultar as notificações de Perfis de Pagamento, 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, revisar as métricas de entrega e tempo de resposta, abrir os detalhes para visualizar o corpo da notificação e reenviá-la quando necessário. Em Teste, os dados são atualizados em tempo real.
A validação da origem de uma notificação é fundamental para garantir a segurança e a autenticidade das informações recebidas. Esse 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 tópico payment_profile.
json{ "id": "abc123def456", "type": "payment_profile", "action": "payment_profile.updated", "version": 3, "date_created": "2026-01-10T10:00:00.000+0000", "live_mode": true, "collector_id": "123456789", "application_id": "1234567890", "data": { "date_last_updated": "2026-03-27T14:30:00.000+0000", "status": "ready", "payment_methods": [ { "unique_id": "pm_001", "type": "credit_card", "status": "ready", "default_method": true, "card_id": 111222333 } ], "previous_attributes": { "status": "pending", "payment_method": { "unique_id": "pm_001", "type": "credit_card", "status": "rejected", "default_method": false, "card_id": 111222333 } } } }
| Campo | Tipo | Presença | Descrição |
id | string | Sempre | Identificador do perfil de pagamento, retornado pela API no momento da criação. |
type | string | Sempre | Sempre payment_profile. |
action | string | Sempre | Sempre payment_profile.updated, indicando que um atributo relevante do perfil foi modificado — status, método de pagamento ou ambos. |
version | integer | Sempre | Contador incremental de notificações para este perfil. Use para ordenar eventos fora de sequência. |
date_created | string | Sempre | Data de criação do perfil (ISO 8601). |
live_mode | boolean | Sempre | true em produção, false em testes. |
collector_id | string | Sempre | ID do vendedor associado ao perfil. |
application_id | string | Sempre | ID da aplicação integradora que originou o perfil. |
data | object | Sempre | Detalhes da mudança ocorrida. |
data.date_last_updated | string | Sempre | Data e hora exata da mudança no perfil, em formato ISO 8601. |
data.status | string | Presente somente se o status foi modificado | Novo status do perfil. |
data.payment_methods | array | Presente somente se houve mudança em um método de pagamento. | Informações atuais dos métodos de pagamento afetados. Inclui o identificador único (unique_id), o tipo de método de pagamento (credit_card, debit_card, prepaid_card, bank_transfer), seu status atual e se está definido como método de pagamento padrão para cobranças (default_method). Se o método de pagamento for um cartão, seu ID (card_id) também estará presente. |
data.previous_attributes | object | Ausente em adições de novos métodos de pagamento. | Informações anteriores dos atributos que mudaram no perfil de pagamento. |
previous_attributes.status | string | Condicional | Status anterior do perfil de pagamento. |
previous_attributes.payment_method | object | Condicional | Estado anterior do método de pagamento afetado. |
Para consultar os valores possíveis de data.status e data.payment_methods[*].status e as ações recomendadas para cada um, consulte Status do perfil e do meio de pagamento.
A partir da notificação recebida, você poderá validar a autenticidade da sua origem por meio da chave secreta. Essa chave será enviada no header x-signature, com o seguinte formato:
plaints=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.
O SDK oficial implementa verificação de assinatura baseada em HMAC (HMAC-based Webhook Signature Verification) para autenticar a origem de cada notificação recebida.
Para obter sua chave secreta (secret), abra a aplicação e, no menu lateral, selecione Configuração de Webhooks. Depois, revele a Assinatura secreta.
<?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 "", 401import "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
endQuando você recebe uma notificação na sua plataforma, o Mercado Pago aguarda uma resposta para validar que o recebimento foi correto. Para isso, retorne um HTTP STATUS 200 ou 201 dentro de 22 segundos após o recebimento.
Recomendamos que você primeiro responda com um 200 ou 201, e depois processe a notificação no servidor, para evitar notificações duplicadas.
Se essa resposta não for enviada, o sistema realizará novas tentativas de envio a cada 15 minutos. Após as primeiras falhas, o intervalo é progressivamente ampliado, mas as entregas continuam até que a notificação seja confirmada.
Após confirmar o recebimento, processe o evento de forma assíncrona. Se a sua integração depende do estado completo do perfil, consulte a API enviando uma requisição para /v1/customers/{customerId}/payment-profiles/{id}GET com o campo id recebido na notificação.
Nunca deduza o estado completo do perfil exclusivamente a partir dos dados da notificação, pois ela envia apenas os campos que foram modificados.