Profesional de software trabajando en una laptop con un panel de control de pagos digitales en la pantalla, en una oficina moderna y luminosa con tono
Configurar webhooks permite que tu servidor reciba datos de pagos y otros eventos de forma automática, sin consultas constantes a la API. Aquí encontrarás cada paso del proceso, junto con recomendaciones de seguridad y solución de errores que la documentación oficial no siempre detalla.
Los webhooks de Mercado Pago se configuran desde el sitio de desarrolladores, dentro de la sección Tus integraciones. Ahí se selecciona la aplicación, se indica la URL de destino y se eligen los eventos a monitorear; al guardar, el sistema genera una firma secreta para validar cada notificación entrante.
A lo largo de este artículo encontrarás los requisitos previos, el paso a paso completo dentro del panel, cómo validar la firma secreta, cómo probar el endpoint antes de salir a producción, y un checklist de diagnóstico para cuando las notificaciones no llegan o se repiten.
Vista cenital de un escritorio de trabajo con manos escribiendo en un teclado mecánico, una pantalla de computadora al fondo muestra interfaces de pro
Qué son los webhooks de Mercado Pago y por qué conviene activarlos
Un webhook es un mecanismo basado en HTTP POST que envía datos de forma automática a tu servidor cada vez que ocurre un evento en Mercado Pago: un pago creado, aprobado, rechazado o una devolución procesada. En lugar de que tu sistema pregunte a la API de forma repetida si algo cambió, es Mercado Pago quien avisa de forma proactiva cuando hay novedades.
La alternativa al webhook es el polling: consultar la API cada cierto tiempo para detectar cambios. Ese enfoque consume recursos del servidor, introduce retrasos y puede generar errores si el volumen de consultas es alto. Con webhooks, la información llega al instante y el servidor solo trabaja cuando hay algo que procesar.
Un ejemplo concreto: una tienda en línea recibe un pago y, en ese momento, Mercado Pago envía una notificación al servidor. El sistema actualiza el estado del pedido, descuenta el inventario y dispara el correo de confirmación, todo sin intervención manual. Ese flujo solo es posible con notificaciones en tiempo real.
Requisitos antes de configurar webhooks en Mercado Pago
Antes de abrir el panel de integraciones, conviene tener todo listo para no interrumpir el proceso a la mitad.
Estos son los elementos que debes tener disponibles:
- Cuenta activa en Mercado Pago con acceso al sitio de desarrolladores (developers.mercadopago.com).
- Una aplicación creada en la sección Tus integraciones; si aún no existe, el siguiente paso del tutorial lo cubre.
- Un servidor con URL pública en HTTPS; localhost no funciona porque Mercado Pago necesita alcanzar tu endpoint desde internet.
- Capacidad de responder con HTTP 200 o 201 en menos de 500 ms; si el servidor tarda más, el sistema interpreta que la notificación no fue recibida.
Si todavía no tienes una aplicación creada en el panel de desarrolladores, el siguiente apartado explica cómo acceder y crearla antes de configurar los webhooks.
Cómo configurar webhooks de Mercado Pago desde el panel de integraciones
El proceso de configuración se realiza dentro del sitio de desarrolladores de Mercado Pago. A continuación se desglosa cada etapa para que puedas seguirla sin saltar pasos.
Acceder a Tus integraciones y seleccionar la aplicación
- Ingresa a developers.mercadopago.com con tu cuenta.
- En el menú principal, selecciona Tus integraciones.
- Elige la aplicación que recibirá las notificaciones. Si no tienes ninguna, haz clic en Crear aplicación, asígnale un nombre y completa los datos básicos.
- Una vez dentro de la aplicación, verás el panel con todas las opciones de configuración disponibles.
Cada aplicación gestiona sus propias credenciales y sus propios webhooks, por lo que el proceso se repite si tienes más de un proyecto activo.
Indicar la URL de notificaciones y elegir eventos
- Dentro de la aplicación, ve a la sección Webhooks y haz clic en Configurar notificaciones.
- Encontrarás dos campos de URL: uno para modo pruebas y otro para modo producción. Completa ambos con los endpoints correspondientes de tu servidor.
- Selecciona los eventos que deseas monitorear. Las opciones incluyen pagos, reembolsos, chargebacks, suscripciones y otros, según la solución integrada.
- Elige solo los eventos que tu negocio necesita. Recibir notificaciones de eventos irrelevantes satura el endpoint sin aportar valor.
Un detalle útil: puedes agregar un query parameter a la URL, por ejemplo ?cliente=tienda_norte, para identificar de qué cuenta proviene cada notificación cuando manejas múltiples cuentas desde un mismo servidor.
Guardar la configuración y obtener la firma secreta
- Haz clic en Guardar para confirmar la configuración.
- El sistema genera una firma secreta exclusiva de esa aplicación. Esta clave aparece una sola vez en pantalla, así que cópiala antes de cerrar.
- Almacena la firma en una variable de entorno de tu servidor, nunca en el código fuente ni en un repositorio público.
- Esta clave se usará para verificar que cada notificación que llega proviene de Mercado Pago y no de un tercero que intente inyectar datos falsos.
La firma secreta es el pilar de la seguridad de tu integración; sin validarla, cualquier persona con acceso a tu URL podría enviar notificaciones fraudulentas.
Monitor mostrando una interfaz de configuración de servidor en un entorno de desarrollo, sobre un escritorio minimalista con una taza de café y auricu
Cómo validar y probar los webhooks de Mercado Pago antes de producción
Antes de pasar a producción, es recomendable comprobar que el endpoint recibe y procesa las notificaciones de forma correcta.
Simular notificaciones desde el panel
El panel de Tus integraciones incluye una opción para enviar una notificación de prueba al endpoint configurado. Para que la simulación sea válida, debes usar las credenciales de prueba del usuario productivo, no las de un usuario de prueba creado ad hoc.
Si aún no tienes un servidor listo para recibir el payload, herramientas como RequestBin o Webhook.site permiten inspeccionar el contenido de cada notificación desde el navegador. Son útiles para verificar la estructura del JSON antes de escribir el código de procesamiento.
Verificar la firma secreta en tu servidor
Cada notificación llega con un header llamado x-signature que contiene un hash generado con tu clave secreta. Para validarlo, tu servidor debe reconstruir ese hash usando los mismos datos y compararlo con el valor del header; si coinciden, la notificación es auténtica.
El proceso de validación no requiere código extenso, pero sí debe ejecutarse antes de procesar cualquier dato del payload. Si la firma no coincide, la notificación debe descartarse sin ejecutar ninguna lógica de negocio.
Un punto que la documentación oficial no siempre enfatiza: tu servidor debe responder con HTTP 200 de forma inmediata, sin esperar a que termine el procesamiento. La lógica de negocio (actualizar base de datos, enviar correos, etc.) debe ejecutarse de forma asíncrona, en un proceso separado. De lo contrario, el tiempo de respuesta puede superar los 500 ms y Mercado Pago interpretará que la notificación no fue recibida.
Checklist de diagnóstico cuando los webhooks de Mercado Pago no llegan
Uno de los problemas más reportados por quienes integran es que las notificaciones no llegan o llegan de forma repetida. Antes de revisar el código, conviene descartar los puntos más comunes:
- La URL es HTTPS y está accesible desde internet. Una URL de localhost o una IP privada no puede recibir notificaciones externas.
- El servidor responde HTTP 200 en menos de 500 ms. Tiempos de respuesta más altos provocan reintentos automáticos.
- No hay firewall ni WAF bloqueando las IPs de Mercado Pago. Algunos proveedores de hosting bloquean rangos de IP por defecto; verifica las reglas de tu servidor.
- Los eventos correctos están seleccionados en el panel. Si el evento no está activado, no se enviará ninguna notificación para ese tipo de acción.
- Se están usando las credenciales correctas. Las credenciales de prueba solo funcionan con la URL de pruebas; las de producción, con la URL de producción.
- Si se reciben reintentos, verificar que la respuesta no sea 4xx ni 5xx. Cualquier código de error en la respuesta indica a Mercado Pago que debe reintentar el envío.
Implementar un sistema de logs que registre cada notificación entrante, con timestamp y código de respuesta, facilita el diagnóstico y reduce el tiempo necesario para identificar el origen del problema.
Buenas prácticas de seguridad y mantenimiento para webhooks
La firma secreta no debe tratarse como un dato estático. Renovarla de forma periódica, sobre todo si hubo una exposición accidental del código fuente, reduce el riesgo de que terceros la usen para enviar notificaciones falsas. El panel de integraciones permite regenerarla cuando sea necesario.
Otro aspecto crítico es la idempotencia: tu servidor debe poder recibir la misma notificación más de una vez sin procesarla dos veces. Mercado Pago puede reenviar notificaciones si no recibe confirmación a tiempo, así que guardar el ID de cada notificación procesada y verificarlo antes de ejecutar la lógica de negocio evita cobros duplicados o actualizaciones incorrectas.
Por último, un endpoint sin monitoreo es un punto ciego. Configurar alertas automáticas que notifiquen cuando el endpoint deja de responder o empieza a devolver errores permite actuar antes de que el problema afecte a quienes compran. Un webhook bien mantenido reduce la intervención manual y sostiene la experiencia de pago sin interrupciones.
Preguntas frecuentes sobre webhooks de Mercado Pago
¿Cuántas URLs de webhook se pueden configurar por aplicación en Mercado Pago?
Se pueden configurar dos URLs por aplicación: una para modo pruebas y otra para modo producción. Cabe aclarar que las URLs indicadas al momento de crear un pago tienen prioridad sobre las configuradas en el panel de integraciones.
¿Qué eventos se pueden monitorear con los webhooks de Mercado Pago?
Los eventos disponibles incluyen pagos (creación y actualización de estado), reembolsos, chargebacks y suscripciones, entre otros. La lista exacta depende de la solución integrada, ya sea Checkout Pro, la API de pagos u otra modalidad.
¿Qué pasa si mi servidor no responde a una notificación webhook?
Mercado Pago reintenta el envío varias veces con intervalos de tiempo crecientes. Si el servidor continúa sin responder con HTTP 200 o 201 tras todos los reintentos, las notificaciones se pierden y no se vuelven a enviar.
¿Se pueden configurar webhooks durante la creación de una preferencia de pago?
Sí. Al crear una preferencia es posible indicar una notification_url en el cuerpo de la solicitud. Esta URL tiene prioridad sobre la configurada en el panel de integraciones, lo que permite personalizar el destino de las notificaciones por transacción.
Si quieres profundizar en la documentación completa de integraciones, el sitio de desarrolladores de Mercado Pago reúne los endpoints, los esquemas de payload y los ejemplos de validación de firma que complementan cada paso de esta guía. Es el punto de partida para quienes buscan llevar la integración a producción con todas las bases cubiertas.
¡Aplican restricciones! Consulta más información sobre productos y promociones en: https://mpago.li/2MdeJDh