Buzón de latón recibiendo una pila de sobres sellados, símbolo de una bandeja de webhooks para disputas de pago

Webhooks de disputas de Stripe: un pipeline de evidencias

•14 min de lectura

La mayoría de los equipos descubre que su manejo de disputas está roto de la misma manera: un contracargo se cierra como perdido porque nadie lo vio a tiempo, o alguien envió media evidencia por accidente. Esta guía trata sobre los webhooks de disputas de Stripe y el sistema que construyes detrás de ellos: cómo recibir los eventos de forma segura, modelar las disputas en tu propia base de datos, armar la evidencia automáticamente a partir de los datos del pedido, dejarla preparada para revisión y no perder nunca un plazo. Está escrita para desarrolladores, CTOs y fundadores técnicos responsables del código de pagos, y se centra en Stripe porque su API de disputas está bien documentada, pero la arquitectura aplica a cualquier procesador.

Si primero quieres el lado de negocio (qué políticas, descriptores y hábitos de servicio al cliente reducen los contracargos antes de que ocurran), lee nuestra guía de 9 pasos para prevenir contracargos en una tienda en línea. Aquí asumimos que la disputa ya existe y la pregunta es cómo responde tu software.

Lo que la plataforma realmente te dice

Antes de diseñar nada, fija los hechos que tu sistema debe respetar:

  • Stripe emite charge.dispute.created, charge.dispute.updated y charge.dispute.closed para el ciclo de vida de la disputa, y radar.early_fraud_warning.created cuando un emisor o una red marca un cargo como potencialmente fraudulento, normalmente antes de una disputa formal.
  • El objeto Dispute expone charge como un ID y un payment_intent que puede ser nulo, así que normalmente necesitas recuperar el Charge para vincular la disputa con tu pedido (documentación de Stripe).
  • Stripe no garantiza el orden de entrega, y las marcas de tiempo de los eventos están en segundos enteros, así que desaconseja ordenar por created y recomienda obtener el objeto actual desde la API (resumen de Chargeflow, citando la documentación de webhooks de Stripe).
  • Según Stripe, normalmente tienes de 7 a 21 días para responder según la red de la tarjeta, y luego el emisor suele tardar de 60 a 75 días en decidir (vía Chargeflow). Tus registros de disputas viven meses, no minutos.
  • En el endpoint de actualización, modificar cualquier campo del hash de evidencia envía todos los campos a revisión, el total combinado de caracteres de todos los campos de evidencia está limitado a 150,000, y submit es true por defecto (Update a dispute).
  • En casos raros, una disputa puede pasar de perdida a ganada fuera del ciclo normal, y un mismo pago puede tener más de una disputa (Chargeflow).

Cada uno de estos puntos se convierte en una regla de diseño más abajo.

Arquitectura: bandeja de entrada, worker, generador de evidencia y programador

Un pipeline de disputas que sobrevive al tráfico real tiene cuatro partes:

  1. Bandeja de entrada de webhooks. Un endpoint HTTP delgado que verifica la firma, guarda el evento crudo una sola vez y responde 2xx. Sin lógica de negocio.
  2. Worker de sincronización. Lee los eventos pendientes, obtiene la Dispute actual desde la API, hace upsert en tu tabla disputes y dispara los efectos secundarios (pausar el envío, revocar acceso, notificar).
  3. Generador de evidencia. Mapea tus datos de pedidos, envíos, inicios de sesión y políticas a los campos de evidencia de Stripe y los deja preparados sin enviarlos.
  4. Programador y conciliador. Escala las disputas que se acercan a evidence_details.due_by y lista periódicamente las disputas desde la API para atrapar cualquier cosa que un webhook no haya entregado.

La separación importa porque las cuatro partes fallan de forma distinta. La bandeja de entrada debe ser rápida y casi nunca fallar; el worker puede reintentar; el generador de evidencia depende de varios sistemas internos que pueden ser lentos; el conciliador es tu red de seguridad cuando todo lo demás falla.

Paso 1: una bandeja de entrada que casi no hace nada

Verifica la firma contra el cuerpo crudo de la petición (parsear el JSON antes rompe la verificación) y luego inserta el evento con su ID como clave única. Las librerías de Stripe aplican por defecto una tolerancia de cinco minutos a la marca de tiempo de la firma, lo que también limita los ataques de repetición (Chargeflow).

app.post("/webhooks/stripe", express.raw({ type: "application/json" }), async (req, res) => {
  let event;
  try {
    event = stripe.webhooks.constructEvent(
      req.body,
      req.headers["stripe-signature"],
      process.env.STRIPE_WEBHOOK_SECRET
    );
  } catch {
    return res.status(400).send("invalid signature");
  }

  // Inserción idempotente: los duplicados se ignoran, no son errores
  await db.query(
    `INSERT INTO webhook_inbox (event_id, type, object_id, payload, received_at)
     VALUES ($1, $2, $3, $4, now())
     ON CONFLICT (event_id) DO NOTHING`,
    [event.id, event.type, event.data.object.id, event]
  );

  res.sendStatus(200); // confirma rápido; el worker hace el trabajo real
});

Compromiso: procesar en línea es más simple y funciona a bajo volumen, pero cualquier llamada lenta (obtener el cargo, subir un archivo, publicar en Slack) arriesga timeouts y reenvíos. Una tabla de bandeja de entrada cuesta una migración y te da la posibilidad de reprocesar, un registro de auditoría y un lugar limpio para medir el retraso.

Paso 2: un modelo de datos que refleja a Stripe sin depender del orden de los eventos

Guarda el estado de Stripe tal cual y mantén tus propios campos operativos junto a él. No intentes calcular el estado a partir de la secuencia de eventos.

CREATE TABLE disputes (
  stripe_dispute_id   text PRIMARY KEY,
  stripe_charge_id    text NOT NULL,
  payment_intent_id   text,             -- puede ser nulo en el objeto de Stripe
  order_id            bigint REFERENCES orders(id),
  amount              integer NOT NULL, -- unidades menores, puede diferir del cargo
  currency            char(3) NOT NULL,
  reason              text NOT NULL,
  stripe_status       text NOT NULL,    -- copiado tal cual desde la API
  due_by              timestamptz,      -- evidence_details.due_by
  evidence_state      text NOT NULL DEFAULT 'none', -- none | drafted | staged | submitted
  owner_user_id       bigint,
  last_synced_at      timestamptz NOT NULL,
  closed_at           timestamptz
);
CREATE INDEX ON disputes (due_by) WHERE evidence_state <> 'submitted';
CREATE INDEX ON disputes (stripe_charge_id); -- un cargo puede tener varias disputas

Fíjate en el índice sobre stripe_charge_id en lugar de una restricción única: como un pago puede disputarse más de una vez, suponer una relación uno a uno entre pedidos y disputas terminará fallando.

Paso 3: el worker consulta y luego hace upsert

El worker trata cada evento como un aviso de que "algo cambió", no como la fuente de verdad. Recupera el objeto y escribe lo que devuelva la API.

async function processDisputeEvent(row) {
  const dispute = await stripe.disputes.retrieve(row.object_id);
  const charge = await stripe.charges.retrieve(dispute.charge);
  const orderId = await findOrderByCharge(charge); // p. ej. desde charge.metadata.order_id

  await db.query(
    `INSERT INTO disputes (stripe_dispute_id, stripe_charge_id, payment_intent_id, order_id,
       amount, currency, reason, stripe_status, due_by, last_synced_at)
     VALUES ($1,$2,$3,$4,$5,$6,$7,$8,to_timestamp($9),now())
     ON CONFLICT (stripe_dispute_id) DO UPDATE SET
       stripe_status = EXCLUDED.stripe_status,
       due_by = EXCLUDED.due_by,
       amount = EXCLUDED.amount,
       last_synced_at = now()`,
    [dispute.id, charge.id, dispute.payment_intent, orderId, dispute.amount,
     dispute.currency, dispute.reason, dispute.status, dispute.evidence_details?.due_by]
  );

  await runSideEffectsOnce(dispute, orderId); // clave: id de disputa + nombre del efecto
  await markProcessed(row.event_id);
}

Como el worker siempre lee el estado más reciente, un charge.dispute.updated tardío que llega después de charge.dispute.closed simplemente vuelve a escribir el mismo estado cerrado. Los efectos secundarios (pausar un envío, suspender una suscripción, avisar al equipo) deben registrarse en una tabla aparte con clave por ID de disputa y nombre del efecto, para que un reintento nunca envíe dos alertas ni cancele dos veces.

Construir la evidencia: se captura en el checkout, no después de la disputa

El generador de evidencia solo puede usar los datos que guardaste cuando ocurrió el pedido. Esta es la parte que la mayoría de los equipos no puede corregir de forma retroactiva, así que diseña el modelo de datos de pedidos pensando en las disputas:

  • Identidad y dispositivo: correo, nombre, dirección de facturación e IP de compra del cliente. Se mapean a campos como customer_email_address, customer_name, billing_address y customer_purchase_ip.
  • Entrega: paquetería, número de guía, fecha de envío y comprobante de entrega, que se mapean a shipping_carrier, shipping_tracking_number, shipping_date y shipping_documentation.
  • Bienes digitales y servicios: eventos de inicio de sesión y uso con marca de tiempo, que se mapean a access_activity_log y service_date.
  • Políticas: la versión exacta de la política de reembolso y cancelación que aceptó el cliente, con marca de tiempo, que se mapea a refund_policy y cancellation_policy.
  • Comunicación: tickets de soporte y correos con el cliente, como archivos o texto.

Los archivos, como comprobantes de entrega o recibos, se suben primero con la Files API (propósito dispute_evidence) y luego se referencian por ID en el hash de evidencia. La referencia de la API de disputas lista todos los campos, y las guías de disputas de Stripe explican qué campos importan para cada motivo, así que el generador debe ramificarse según dispute.reason en lugar de mandar todo cada vez.

function buildEvidence(dispute, order) {
  const base = {
    customer_email_address: order.email,
    customer_name: order.customerName,
    customer_purchase_ip: order.purchaseIp,
    product_description: order.summary,
  };
  switch (dispute.reason) {
    case "product_not_received":
      return { ...base,
        shipping_carrier: order.carrier,
        shipping_tracking_number: order.trackingNumber,
        shipping_date: order.shippedOn,
        shipping_documentation: order.deliveryProofFileId };
    case "subscription_canceled":
      return { ...base,
        cancellation_policy: order.cancellationPolicyFileId,
        access_activity_log: order.accessLogText };
    default:
      return { ...base, uncategorized_text: order.timelineText };
  }
}

Mantén el texto generado muy por debajo del límite combinado de 150,000 caracteres. Una cronología concisa con fechas es mejor que un volcado de logs crudos, tanto por el límite como por la persona del banco que la lee.

Primero preparar, luego enviar de forma deliberada

El valor por defecto más peligroso de esta API es submit: true. Si cualquier proceso actualiza la evidencia sin pasar explícitamente submit: false, Stripe envía todo de inmediato, y la documentación de arbitraje advierte que agregar o actualizar evidencia sin submit=false envía toda la evidencia preparada. En la práctica, un borrador automático a medio terminar puede convertirse en tu respuesta final.

// Generador automático: siempre preparar (staging)
await stripe.disputes.update(dispute.id, {
  evidence: buildEvidence(dispute, order),
  submit: false,
});

// La aprobación humana (o una regla explícita) dispara el envío real
await stripe.disputes.update(dispute.id, { submit: true });

Envuelve el cliente de Stripe para que la única ruta de código capaz de enviar submit: true sea la acción de aprobación, y haz que esa ruta revise primero evidence_state y el stripe_status actual. Pasa una clave de idempotencia en estas peticiones POST para que una aprobación reintentada no cause una doble actualización confusa.

Smart Disputes frente a tu propio generador

Stripe ofrece Smart Disputes para automatizar la recopilación y el envío de evidencia en disputas elegibles, y el objeto Dispute expone una configuración con valores como manual, prefer_manual, prefer_smart_disputes y smart_disputes que deciden qué paquete se usa (objeto Dispute). El compromiso es claro: Smart Disputes usa lo que Stripe ya sabe y requiere poca ingeniería; tu propio generador puede incluir evidencia que Stripe nunca ve, como fotos de entrega, uso dentro de la app o conversaciones de soporte. Muchos equipos combinan ambos: dejan que la automatización atienda los casos de bajo valor y envían los de alto valor o ambiguos al pipeline manual. Elijas lo que elijas, haz la elección explícita en la configuración en lugar de dejarla depender de qué código tocó primero la disputa.

Plazos, conciliación y alertas tempranas

Programador de plazos. Ejecuta un job que seleccione las disputas donde evidence_state <> 'submitted' y due_by se acerca, y que escale por niveles (responsable y luego líder del equipo). Calcula y muestra siempre los plazos en UTC junto con la hora local de quien revisa; de lo contrario, los equipos repartidos entre Ciudad de México, Bogotá y Estados Unidos discutirán qué significa "vence mañana".

Conciliador. Los webhooks pueden fallar: un endpoint estuvo caído más tiempo que la ventana de reintentos, un secreto se rotó mal o nunca se suscribió un tipo de evento. Un job diario que liste las disputas recientes y las compare con tu tabla atrapa todos estos casos.

for await (const d of stripe.disputes.list({ created: { gte: thirtyDaysAgo }, limit: 100 })) {
  const local = await getDispute(d.id);
  if (!local || local.stripe_status !== d.status) {
    await enqueueSync(d.id); // misma ruta de código que el worker de webhooks
  }
}

Reutilizar la ruta de código del worker es importante: una conciliación que escribe en la base de datos con otra función terminará desalineándose.

Alertas tempranas de fraude. En muchos casos, radar.early_fraud_warning.created llega antes de una disputa formal. Envíalo a la misma bandeja de entrada y decide con una regla si reembolsar de forma proactiva, cancelar la entrega o solo marcar el pedido. Reembolsar evita la disputa pero renuncia al ingreso; pelear conserva la opción de ganar pero arriesga una disputa que cuenta en tu contra. Haz que la regla dependa del monto, de si el pedido ya se envió y de si el cliente tiene historial contigo.

Apelaciones. Si una disputa pasa a prearbitraje, Stripe acepta evidencia mediante evidence.appeal y, según su documentación, no enviarla en 20 días significa que asumes implícitamente la responsabilidad (documentación de arbitraje de Stripe). Modélalo como otra ronda de evidencia sobre la misma disputa, con su propio plazo.

Errores comunes

  • Parsear el cuerpo JSON antes de verificar la firma, de modo que todas las verificaciones fallan en producción.
  • Ejecutar lógica de negocio dentro del handler del webhook y sufrir timeouts con carga.
  • Derivar el estado de la disputa del orden de los eventos en lugar de consultar el objeto.
  • Suponer una disputa por pedido, o que el monto disputado es igual al monto del cargo.
  • Permitir que código automático actualice la evidencia sin submit: false.
  • No guardar en el checkout la IP de compra, la versión de la política ni el comprobante de entrega, y luego intentar reconstruirlos semanas después.
  • No tener un job de conciliación, de modo que un webhook perdido se convierte en un plazo perdido.
  • Ejecutar efectos secundarios (correos, cancelaciones) sin deduplicación.

Checklist de implementación

  1. Suscríbete a charge.dispute.created, charge.dispute.updated, charge.dispute.closed y radar.early_fraud_warning.created.
  2. Verifica las firmas sobre el cuerpo crudo; guarda los eventos en una bandeja de entrada con ID de evento único.
  3. Procesa de forma asíncrona; recupera siempre la Dispute y el Charge actuales desde la API.
  4. Modela las disputas con el estado de Stripe tal cual, due_by, estado de la evidencia, responsable y vínculo con el pedido.
  5. Captura los datos de evidencia en el checkout y en la entrega, incluidas las versiones de las políticas.
  6. Construye la evidencia según el motivo; sube los archivos con el propósito dispute_evidence.
  7. Prepara con submit: false; limita submit: true a una ruta de aprobación.
  8. Escala los plazos que se acercan; concilia a diario contra la API.
  9. Deduplica los efectos secundarios; registra cada cambio de evidencia para auditoría.

Si tu tienda corre sobre un stack propio y este pipeline abarca sistemas de checkout, entregas y soporte, este es el tipo de integración que diseñamos en nuestros proyectos de software a la medida. Para tiendas que aún se están planeando, es mucho más barato incluir los campos de evidencia en la tienda en línea desde el primer día que agregarlos después.

Preguntas frecuentes

¿Necesito una cola o basta con una tabla en la base de datos para la bandeja de entrada?

Para la mayoría de las tiendas basta con una tabla con ID de evento único y un worker que la consulte periódicamente, y es más fácil de inspeccionar y reprocesar. Pasa a una cola dedicada cuando el volumen o los requisitos de latencia hagan impráctico el sondeo; conserva el ID de evento único en cualquier caso.

¿Puedo confiar en el objeto de disputa que viene dentro del payload del webhook?

Es una foto del momento en que se creó el evento. Como el orden de entrega no está garantizado, consulta la Dispute actual desde la API antes de escribir el estado, y usa el payload solo para saber qué objeto consultar.

¿Debería automatizar por completo el envío de evidencia?

Solo cuando confíes en los datos y el caso sea de bajo riesgo. Como cualquier actualización de evidencia se envía por defecto, mantén el código automático con submit: false y exige una aprobación explícita, humana o basada en reglas, para el envío final.

Comentarios

Todavía no hay comentarios. Sé el primero en compartir lo que piensas.

Deja un comentario

Nunca se publica.