Webhooks (también conocido como devolución de llamada web) es un método simple que facilita que una aplicación o sistema proporcione información en tiempo real cada vez que ocurre un evento, es decir, es una forma de recibir datos pasivamente entre dos sistemas a través de un HTTP POST.

Las notificaciones Webhooks se pueden configurar para una o más aplicaciones creadas en Tus integraciones. También es posible configurar una URL de prueba que, junto con las credenciales de prueba, permitirá verificar el correcto funcionamiento de las notificaciones previo a salir a producción.

Una vez configurada, la notificación Webhook será enviada cada vez que ocurra uno o más eventos registrados, evitando la necesidad de verificaciones constantes y, consecuentemente, previniendo la sobrecarga del sistema y la pérdida de datos en situaciones críticas.

Para configurar notificaciones Webhooks, puedes elegir una de las opciones a continuación.

Una vez que las notificaciones sean configuradas, consulta las acciones necesarias después de recibir una notificación para validar que las mismas fueron debidamente recibidas.

Puedes configurar notificaciones para cada una de tus aplicaciones directamente desde Tus integraciones de manera eficiente y segura. En este apartado, explicaremos cómo:

1. Indicar las URLs de notificación y configurar eventos
2. Validar el origen de una notificación
3. Simular el recibimiento de una notificación

Para configurar notificaciones Webhooks mediante Tus integraciones, es necesario indicar las URLs a las que las mismas serán enviadas y especificar los eventos para los cuales deseas recibirlas.

Para hacerlo, sigue el paso a paso a continuación:

1. Ingresa a Tus Integraciones y selecciona la aplicación para la que deseas activar las notificaciones. En caso de que aún no hayas creado una aplicación, accede a la documentación sobre el Panel del Desarrollador y sigue las instrucciones para poder hacerlo.
2. En el menú de la izquierda, selecciona Webhooks > Configurar notificaciones, y configura las URLs que serán utilizadas para recibirlas. Recomendamos utilizar dos URLs diferentes para el modo de pruebas y el modo producción:
   • URL modo pruebas: proporciona una URL que permita probar el correcto funcionamiento de las notificaciones de la aplicación durante la etapa de desarrollo. La prueba de estas notificaciones deberá ser realizada exclusivamente con credenciales de prueba del usuario productivo con el que creaste la aplicación.
   • URL modo producción: proporciona una URL para recibir notificaciones con tu integración productiva. Estas notificaciones deberán ser configuradas con tus credenciales productivas.

3. Selecciona los eventos de los que recibirás notificaciones, que serán enviadas en formato JSON a través de un HTTP POST a la URL especificada anteriormente. Un evento puede ser cualquier actualización sobre el tópico reportado, incluyendo cambios de status o atributos. Consulta la tabla a continuación para ver qué eventos pueden ser configurados teniendo en cuenta la solución de Mercado Pago integrada y las particularidades de negocio.

4. Por último, haz clic en Guardar. 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.

Las notificaciones enviadas por Mercado Pago serán semejantes al siguiente ejemplo para un alerta del tópico payment:

json
Copiar
{
 "id": 12345,
 "live_mode": true,
 "type": "payment",
 "date_created": "2015-03-25T10:04:58.396-04:00",
 "user_id": 44444,
 "api_version": "v1",
 "action": "payment.created",
 "data": {
     "id": "999999999"
 }
}

Mercado Pago siempre incluirá la clave secreta en las notificaciones Webhooks que serán recibidas, lo que permitirá validar su autenticidad para proporcionar mayor seguridad y prevenir posibles fraudes.

Esta clave será enviada en el header x-signature, que será similar al ejemplo debajo.

x-signature
Copiar
`ts=1704908010,v1=618c85345248dd820d5fd456117c2ab2ef8eda45a0282ff693eac24131a5e839`

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 esa recepción fue correcta. Para eso, debes devolver un HTTP STATUS 200 (OK) o 201 (CREATED).

El tiempo de espera para esa confirmación será de 22 segundos. Si no se envía esta respuesta, el sistema entenderá que la notificación no fue recibida y realizará un nuevo intento de envío cada 15 minutos, hasta que reciba la respuesta. Después del tercer intento, el plazo será prorrogado, pero los envíos continuarán sucediendo.

Luego de responder la notificación, confirmando su recibimiento, puedes obtener toda la información sobre el recurso notificado haciendo una requisición al endpoint correspondiente. Para identificar qué endpoint debes utilizar, consulta la tabla debajo:

Con esta información podrás realizar las actualizaciones necesarias a tu plataforma, como actualizar un pago aprobado.

El panel de notificaciones es una herramienta que permite visualizar los eventos disparados sobre una determinada integración, verificar el estado de las notificaciones, y obtener información detallada sobre esos eventos.

Este Panel será exhibido una vez que hayas configurado tus notificaciones Webhooks, y puedes acceder a él cuando desees, haciendo clic en Webhooks dentro de Tus integraciones.

Entre la información disponible en este panel, encontrarás el porcentaje de notificaciones entregadas, así como una visión rápida de cuáles son las URLs y eventos configurados.

Además, encontrarás una lista completa de las últimas notificaciones enviadas y sus detalles, como estado de la entrega (exitoso o fallido), acción (acción asociada al evento disparado), evento (tipo de evento disparado), y fecha y hora. Si lo deseas, es posible filtrar estos resultados exhibidos por estado de la entrega y por período.

Al hacer clic en una de las notificaciones listadas, podrás acceder a los detalles del evento. Esta sección proporciona mayor información y permite recuperar datos perdidos en caso de fallas en la entrega de la notificación para mantener tu sistema actualizado.

• Status: Estado del evento junto con el código de éxito o error correspondiente.
• Evento: Tipo de evento disparado, en función de los tópicos seleccionados durante la configuración de las notificaciones.
• Tipo: Tópico al que pertenece el evento disparado, en función de la selección hecha durante la configuración.
• Fecha y hora del disparo: Fecha y hora en la que fue disparado el evento.
• Descripción: Descripción detallada del evento.
• ID del disparo: Identificador único de la notificación enviada.
• Requisición: JSON del llamado enviado como notificación.

En caso de una falla en la entrega de la notificación, podrás conocer cuáles fueron los motivos y rectificar la información necesaria para evitar futuros problemas.