Webhooks

Diseña un handler seguro para webhooks de Cobru y entiende las limitaciones actuales del callback.

Cobru envía un POST a la URL callback que incluyes al crear un pago. Hoy esta es la vía principal para reaccionar a actualizaciones de pago desde tu propio backend.

Empieza aquí

Trata el callback como notificación, no como fuente de verdad.
Persiste el evento raw inmediatamente.
Responde HTTP 200 rápido.
Deduplica por identificadores Cobru o por tu propia referencia de pago.
Reconcilia antes de liberar valor irreversible.

Modelo de confianza actual

Los webhooks de Cobru no están firmados hoy. No existe un contrato público de HMAC header o verificación JWT. Trata el webhook como notificación, no como prueba definitiva.

Payload típico

{
  "orderId": "123",
  "state": 3,
  "payment_method": "Bre-B",
  "amount": "50000.00",
  "url": "3gofdf6f"
}

Estados de pago

Estado	Significado	Notas
`0`	Creado / pendiente	el objeto de pago existe
`1`	Procesando	el usuario inició o Cobru espera confirmación final
`2`	No pagado / rechazado	el resultado depende del método
`3`	Pagado / aprobado	el estado que la mayoría de equipos trata como settlement exitoso
`4`	Reembolsado	reembolso aplicado
`5`	Expirado	aparece en materiales históricos de Cobru; confírmalo antes de depender de él

Qué debe hacer una integración segura de webhooks

Recibir el callback, parsear el JSON y persistir el payload raw de inmediato.

Responder HTTP 200 rápido para que Cobru no dependa del tiempo de tu procesamiento downstream.

Deduplicar por orderId, url o tu propia referencia interna del pago.

Reconciliar el pago antes de despachar bienes, liberar valor o marcar éxito irreversible.

Patrón recomendado para el handler

Parsea el payload.
Persiste el evento inmediatamente.
Responde HTTP 200 lo más rápido posible.
Procesa reconciliación y side effects de forma asincrónica.
Protege acciones downstream con idempotencia usando orderId o tu propia referencia.

export async function POST(request: Request) {
  const payload = await request.json();

  await saveWebhookEvent(payload);

  return new Response('ok', { status: 200 });
}

Modelo de persistencia recomendado

Guarda al menos:

payload raw
timestamp de recepción
order ID interno
slug url de Cobru
orderId de Cobru cuando exista
resultado del procesamiento
contador de replay o marca de deduplicación

Opciones de hardening disponibles hoy

Riesgo	Workaround actual
cualquiera puede golpear tu callback	incluye tu propio secreto en el query string del callback
entregas duplicadas	guarda `orderId` y salta eventos ya procesados
spoofing del callback	vuelve a consultar detalles del pago con Cobru antes de liberar valor
puntos ciegos operativos	loguea todos los callbacks y expón una herramienta interna de replay

Qué no debes hacer

no marques una orden como definitivamente exitosa antes de reconciliar
no ejecutes trabajo pesado downstream antes de responder 200
no confíes solo en la IP de origen como control de seguridad
no asumas que los callbacks llegan exactamente una sola vez

Pruebas locales

ngrok http 3000

Luego usa esa URL pública HTTPS como tu valor callback en sandbox.

Controles recomendados para producción

Control	Por qué importa
secreto en callback o token no adivinable	reduce riesgo de spoofing trivial
event log persistente	permite depurar incidentes y replays
procesador idempotente	protege contra duplicados
paso de reconciliación	evita falsos positivos cuando el callback es incompleto o falso
alertas sobre fallas de procesamiento	reduce errores silenciosos en pagos

Sigue con

/docs/testing
/docs/production-readiness
/docs/troubleshooting
/docs/api/cobrus/create

Webhooks

On this page