Saltar a contenido

Webhooks

Recepción y procesamiento de notificaciones de MercadoPago Point.

Flujo

sequenceDiagram
    participant MP as MercadoPago
    participant API as Integration API
    participant DB as D1

    MP->>API: POST /webhooks (x-signature + payload)
    API->>API: Validar HMAC-SHA256
    alt Firma inválida
        API-->>MP: 401 Unauthorized
    else Firma válida
        API->>DB: Guardar webhook log
        API->>DB: Actualizar estado orden
        API-->>MP: 200 OK
    end

Validación de firma

MercadoPago firma cada webhook con HMAC-SHA256. El header x-signature tiene el formato:

x-signature: ts=1234567890,v1=abc123def456...

La validación construye el manifest:

id:{data.id};request-id:{x-request-id};ts:{timestamp};

Y verifica el hash con el WEBHOOK_SECRET configurado, con tolerancia de 5 minutos en el timestamp.

Eventos soportados

Action Estado Descripción
order.processed processed Pago exitoso
order.canceled canceled Orden cancelada
order.expired expired Orden expiró
order.failed failed Pago rechazado
order.action_required action_required Requiere acción del operador
order.refunded refunded Reembolso total procesado
order.partially_refunded partially_refunded Reembolso parcial procesado

Payload de ejemplo

{
  "action": "order.processed",
  "api_version": "v1",
  "application_id": "4577471269195414",
  "data": {
    "external_reference": "TICKET-00001",
    "id": "ORDTST01...",
    "status": "processed",
    "status_detail": "accredited",
    "total_paid_amount": "1500.50",
    "transactions": {
      "payments": [
        {
          "amount": "1500.50",
          "id": "PAY01...",
          "paid_amount": "1500.50",
          "payment_method": {
            "id": "visa",
            "installments": 1,
            "type": "credit_card"
          },
          "status": "approved",
          "status_detail": "accredited"
        }
      ]
    },
    "type": "point",
    "version": 3
  },
  "date_created": "2025-02-20T15:30:00.000Z",
  "live_mode": true,
  "type": "order",
  "user_id": "241983636"
}

Webhook de reembolso

{
  "action": "order.refunded",
  "data": {
    "status": "refunded",
    "status_detail": "refunded",
    "transactions": {
      "payments": [
        {
          "amount": "1500.50",
          "id": "PAY01...",
          "refunded_amount": "1500.50",
          "status": "refunded"
        }
      ],
      "refunds": [
        {
          "amount": "1500.50",
          "status": "processed",
          "transaction_id": "PAY01..."
        }
      ]
    }
  }
}

Configuración en MercadoPago

La URL del webhook se configura en la aplicación de MercadoPago:

https://mercadopago.histrix.com.ar/webhooks

El WEBHOOK_SECRET se obtiene desde el panel de MercadoPago y se configura en .dev.vars o en las variables de Cloudflare.