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]
    

Configurar Webhooks

Siga o passo a passo abaixo para configurar as notificações de Perfis de Pagamento.

1. Acesse Suas integrações e selecione a aplicação para a qual deseja ativar as notificações.

2. No menu da esquerda, selecione Webhooks > Configurar notificações.

3. Configure as URLs que receberão as notificações. Recomendamos usar URLs separadas para os modos de teste e produção:

   • URL modo teste: use durante o desenvolvimento, exclusivamente com as credenciais de testeChaves de acesso vinculadas a uma aplicação, utilizadas para testar a integração em um ambiente seguro. Você pode consultá-las na seção Credenciais da aplicação, dentro do ambiente de teste. Elas não permitem processar pagamentos reais..
   • URL modo produção: use com sua integração já em produção, configurada com credenciais produtivasChaves de acesso vinculadas a uma aplicação, utilizadas para processar operações reais. Você pode consultá-las na seção Credenciais da aplicação, dentro do ambiente de produção. Use a Public Key no frontend e o Access Token no backend..

4. Selecione o evento Perfil de Pagamento (payment_profile) para receber notificações de mudanças no perfil.

5. Por fim, clique em Salvar configuração. Isso gerará uma chave secreta exclusiva para a aplicação, que permitirá validar a autenticidade das notificações recebidas, garantindo que foram enviadas pelo Mercado Pago. Esta chave não tem prazo de validade e a renovação periódica não é obrigatória, embora seja recomendada. Para fazê-lo, basta clicar no botão Redefinir.

Simular o recebimento da notificação

Para garantir que as notificações estejam configuradas corretamente, simule o recebimento seguindo o passo a passo abaixo.

1. Após configurar a URL e o evento, clique em Salvar configuração.
2. Em seguida, clique em Simular para verificar se a URL indicada está recebendo as notificações corretamente.
3. Na tela de simulação, selecione a URL a ser testada.
4. Escolha o tipo de evento Perfil de Pagamento e insira o ID do perfil que será enviado no corpo da notificação (Data ID).
5. Por fim, clique em Enviar teste para verificar a solicitação, a resposta do servidor e a descrição do evento.

Validar a origem da notificação

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
      }
    }
  }
}

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:

plain
ts=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 Suas integrações. Siga uma das abordagens abaixo para validar a autenticidade da notificação.

<?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 "", 401

import "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
end

Ações necessárias após receber a notificação

Quando 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.