Las notificaciones Webhooks de Perfiles de Pago notifican a tu aplicación en tiempo real cada vez que un perfil vinculado a tu integración sufre un cambio relevante. En lugar de consultar la API periódicamente, recibes las actualizaciones en el momento en que ocurren mediante un HTTP POST.

De esta manera, es posible detectar cuando un perfil alcanza el estado ready para habilitar el flujo de cobros recurrentes, realizar las acciones necesarias ante la inactivación o cancelación de un método de pago asociado a un perfil y mantener tu sistema siempre sincronizado con el estado real.

    flowchart TD
        A[Cambio en el perfil] --> B{Verifica elegibilidad}
        B -->|No elegible| C[Evento descartado]
        B -->|Elegible| D["POST {tu-url} con payload JSON"]
        D --> E[Tu aplicación responde HTTP 200]
        E --> F[Procesa el evento de forma asíncrona]
    

Sigue el paso a paso a continuación para configurar las notificaciones de Perfiles de Pago.

1. Accede a Tus integraciones y selecciona la aplicación para la que deseas activar las notificaciones.

2. En el menú de la izquierda, selecciona Webhooks > Configurar notificaciones.

3. Configura las URLs que recibirán las notificaciones. Recomendamos usar URLs separadas para los modos de prueba y producción:
   • URL modo test: úsala durante el desarrollo, exclusivamente con las credenciales de pruebaCredenciales únicas con las que identificas tu integración en entornos de prueba..
   • URL modo producción: úsala con tu integración ya en producción, configurada con credenciales productivasCredenciales únicas con las que identificas tu integración en entornos de producción..
4. Selecciona el evento Perfil de Pago (payment_profile) para recibir notificaciones de cambios en el perfil.
5. Por último, haz clic en Guardar configuración. Esto generará una clave secreta exclusiva para la aplicación, que permitirá validar la autenticidad de las notificaciones recibidas, garantizando que hayan sido enviadas por Mercado Pago. Ten en cuenta que esta clave generada no tiene plazo de caducidad y su renovación periódica no es obligatoria, aunque sí recomendada. Para hacerlo, basta con cliquear en el botón Restablecer.

Para garantizar que las notificaciones estén configuradas correctamente, simula su recepción siguiendo el paso a paso a continuación.

1. Después de configurar la URL y el evento, haz clic en Guardar configuración.
2. Luego, haz clic en Simular para verificar que la URL indicada está recibiendo las notificaciones correctamente.
3. En la pantalla de simulación, selecciona la URL que se va a probar.
4. Elige el tipo de evento Perfil de Pago e ingresa el ID del perfil que se enviará en el cuerpo de la notificación (Data ID).
5. Por último, haz clic en Enviar prueba para verificar la solicitud, la respuesta del servidor y la descripción del evento.

La validación del origen de una notificación es fundamental para asegurar la seguridad y la autenticidad de la información recibida. Este proceso ayuda a prevenir fraudes y garantiza que solo las notificaciones legítimas sean procesadas.

Mercado Pago enviará a tu servidor una notificación similar al ejemplo a continuación para una alerta del tópico payment_profile.

json
Copiar
{
  "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 los valores posibles de data.status y data.payment_methods[*].status y las acciones recomendadas para cada uno, consulta Estados del perfil y del medio de pago.

A partir de la notificación recibida, podrás validar la autenticidad de su origen a través de la clave secreta. Esta clave será enviada en el header x-signature, con el siguiente formato:

plain
Copiar
ts=1742505638683,v1=ced36ab6d33566bb1e16c125819b8d840d6b8ef136b0b9127c76064466f5229b

Para confirmar la validación, es necesario extraer la clave contenida en el header y compararla con la clave otorgada para tu aplicación en Tus integraciones.

Sigue uno de los enfoques a continuación para validar la autenticidad de la notificación.

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

Cuando recibes una notificación en tu plataforma, Mercado Pago espera una respuesta para validar que la recepción fue correcta. Para eso, devuelve un HTTP STATUS 200 o 201 dentro de los 22 segundos siguientes a la recepción.

Recomendamos que primero respondas con un 200 o 201, y que luego proceses la notificación en el servidor, para evitar notificaciones duplicadas.

Si no se envía esta respuesta, el sistema realizará nuevos intentos de envío cada 15 minutos. Después de los primeros fallos, el intervalo se amplía progresivamente, pero las entregas continúan hasta que la notificación sea confirmada.

Luego de confirmar la recepción, procesa el evento de forma asíncrona. Si tu integración depende del estado completo del perfil, consulta la API enviando una solicitud a /v1/customers/{customerId}/payment-profiles/{id}GET con el campo id recibido en la notificación.

Nunca deduzcas el estado completo del perfil exclusivamente a partir de los datos de la notificación, pues esta envía solo los campos que sufrieron modificaciones.