Webhooks

Tras un cambio de estado de pago o retiro, Cobrex envía una petición HTTP a la URL configurada para el comerciante o al callback indicado al crear la operación.

Cuerpo de la petición

Operación	Cuerpo
Pago	JSON del objeto de pago (véase modelo).
Retiro	JSON del objeto de retiro (véase modelo).

Confirme método y cabeceras con la especificación vigente; use las comprobaciones siguientes para seguridad.

Respuesta de su servidor

Si el webhook está aceptado y procesado (o encolado internamente con garantía de procesamiento), el endpoint debe responder HTTP 200. Cobrex lo interpreta como entrega correcta.

Cualquier otro resultado (5xx, 4xx, tiempo de espera agotado, corte de conexión) cuenta como fallo y activa los reintentos siguientes.

Reintentos tras un fallo

Si la entrega no es exitosa, Cobrex programa otro intento con demora creciente:

• El contador de intentos aumenta mientras sea menor que 9.
• Con 9 o más intentos en este ciclo, no hay más reintentos (next_attempt_at queda sin fecha).
• La demora hasta el siguiente intento depende del valor actual de attempts al planificar.

Demora hasta el siguiente intento:

attempts al planificar	Espera hasta la siguiente entrega
1	10 segundos
2	30 segundos
3	1 minuto
4	5 minutos
5	15 minutos
6	1 hora
7	4 horas
8	16 horas
Otros valores cubiertos (reserva de implementación)	15 minutos

Puede recibir hasta nueve rondas fallidas antes de que cesen los reintentos; confirme el comportamiento en producción con el soporte Cobrex si cambia la política.

Comprobación 1 — dirección IP

Permita solo IP de confianza. En el momento de esta documentación:

46.166.162.83

Las listas pueden cambiar — confirme la lista de producción con soporte.

Comprobación 2 — cabecera x-signature

1. Guarde el cuerpo en bruto como cadena/búfer antes de JSON.parse.
2. HMAC-SHA256 con su secreto (el mismo que la API, o un secreto dedicado — confirme con Cobrex).

Patrón habitual:

signature_hex = HMAC-SHA256( key = api_secret, message = JSON.stringify(data) ).toString('hex')

En la práctica, verificar HMAC sobre la cadena del cuerpo en bruto suele ser más estable:

const crypto = require('crypto');

function verifyWebhookSignature(rawBodyString, receivedHex, apiSecret) {
  const expected = crypto.createHmac('sha256', apiSecret).update(rawBodyString).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(receivedHex, 'hex'));
}

Confirme con Cobrex qué variante usa producción.

Recomendaciones

• Responda HTTP 200 enseguida tras validar y encolar; ejecute el trabajo pesado de forma asíncrona.
• Haga el manejador idempotente por payment_id / payout_id.
• Registre cabeceras y cuerpos en depuración (nunca secretos).

Véase también: Autenticación y firma.