Reintentos y entrega

Certivant está diseñado para entregar cada evento al menos una vez. Si su endpoint no está disponible durante un momento (un despliegue, un fallo breve de la base de datos, una caída de 30 segundos), los reintentos garantizan que el evento llegue igualmente. Esta página explica el comportamiento exacto para que pueda planificarlo.

La política de reintentos de un vistazo

Tras el quinto intento fallido, el evento se marca como agotado. No se reintentará automáticamente. Se envía un correo al propietario de la organización para avisarle de que los webhooks están fallando.

La línea de tiempo

gantt
  title Webhook delivery attempts
  dateFormat X
  axisFormat %s
  section Attempts
  Attempt 1 (immediate) :a1, 0, 1s
  Attempt 2 (+5s)       :a2, 5, 1s
  Attempt 3 (+30s)      :a3, 35, 1s
  Attempt 4 (+5min)     :a4, 335, 1s
  Attempt 5 (+1h)       :a5, 3935, 1s
  Attempt 6 (+24h)      :a6, 90335, 1s

El reloj empieza cuando se genera el evento. Si su endpoint está sano en el primer intento, nunca verá reintentos. Si está caído durante las ~25 horas completas, el evento se agota.

Qué cuenta como éxito

Certivant considera que su endpoint está sano cuando:

• El estado HTTP es 2xx (200, 201, 204, etc.).
• La respuesta llega en menos de 10 segundos desde el envío de la petición.

Cualquier otra cosa es un fallo de entrega:

• Redirecciones 3xx: Certivant no sigue las redirecciones. Apunte la URL del webhook al destino final.
• 4xx (incluidos 401 y 404): Certivant reintenta de todos modos, por si el problema es transitorio (una comprobación de autenticación en arranque en frío, una ruta que aún no se ha desplegado). La mayoría de las integraciones deberían investigar cualquier 4xx: normalmente indica una mala configuración en su lado.
• 5xx: error del servidor. Reintento estándar.
• Conexión rechazada, fallo de DNS, error en el handshake TLS: el mismo comportamiento de reintento.
• Sin respuesta en 10 segundos: Certivant aborta la petición y la cuenta como fallo. Los reintentos continúan.

Cómo diseñar un manejador rápido

Tiene un presupuesto de 10 segundos. Haga lo mínimo de forma síncrona:

app.post("/webhooks/certivant", async (c) => {
  const rawBody = await c.req.text();

  // 1. Verify signature
  if (!verifyCertivantSignature(rawBody, c.req.header("X-Certivant-Signature-V2"), SECRET)) {
    return c.json({ error: "Invalid signature" }, 401);
  }

  // 2. Persist to queue (single DB write, fast)
  const eventId = c.req.header("X-Certivant-Event-Id")!;
  await db.webhookEventQueue.create({
    data: { id: eventId, payload: rawBody },
  });

  // 3. Acknowledge immediately
  return c.json({ received: true }, 200);
});

// Process the queue asynchronously
async function workerLoop() {
  while (true) {
    const event = await db.webhookEventQueue.findFirst({ where: { processedAt: null } });
    if (!event) { await sleep(1000); continue; }
    try {
      await handleEvent(JSON.parse(event.payload));
      await db.webhookEventQueue.update({ where: { id: event.id }, data: { processedAt: new Date() } });
    } catch (err) {
      // Bounded retry on your side; surface after N attempts
    }
  }
}

Este patrón separa la confirmación (que debe ser rápida) de la lógica de negocio (que puede ser lenta o reintentarse de forma independiente). Sus servicios posteriores (envío de correos de bienvenida, aprovisionamiento de cuentas, etc.) pueden fallar sin que Certivant reintente.

Cuando su endpoint está realmente caído

Si va a estar caído durante un periodo prolongado (mantenimiento, migración), los reintentos le cubrirán durante unas 25 horas. Más allá de eso:

• Los eventos agotados siguen siendo consultables mediante GET /api/v1/kyc/requests/:id: el estado actual siempre está disponible en la propia solicitud. Recorra las solicitudes creadas durante su caída y sincronice el estado manualmente.
• El propietario de la organización recibe un correo cuando un evento se agota. El correo incluye el ID de la solicitud para que sea fácil buscarla.
• El estado de entrega del webhook (entregado / fallido / agotado), el número de intentos, el último código de respuesta y el siguiente reintento programado son visibles en el panel, en KYC → Configuración → Webhooks → Registro de entregas, donde cada evento fallido o agotado tiene un botón Reintentar ahora (y reintento masivo).

Volver a entregar un evento agotado

Desde el registro de entregas, Reintentar ahora vuelve a enviar de inmediato un evento fallido o agotado, firmado con el secreto actual, y reinicia su contador de intentos. No existe un endpoint público (con clave de API) para relanzar un evento concreto. Otras opciones:

1. Obtener el estado mediante la API. GET /api/v1/kyc/requests/:id devuelve siempre el estado actual, incluida la decisión final. Es la respuesta correcta para ponerse al día tras una caída.
2. Pedir a soporte que reenvíe si le falta un lote grande. Incluya los ID de las solicitudes o la ventana temporal: soporte puede volver a emitir los eventos por usted.

Interacción con el límite de solicitudes

La entrega de webhooks no consume el límite de solicitudes de su clave de API: son sistemas separados. Puede recibir cientos de webhooks por minuto mientras hace cientos de llamadas a la API por minuto con la misma clave, y ninguno de los dos presupuestos afecta al otro.

Idempotencia, de nuevo

Como existen los reintentos, el mismo evento lógico llegará a veces dos veces. Consulte Eventos → Idempotencia para el patrón de deduplicación recomendado con X-KYC-Event-Id.

Sugerencias de monitorización

Una integración de webhooks sana tiene:

• Un tiempo de respuesta mediano del endpoint de webhook por debajo de 500 ms. Si aumenta, corre el riesgo de alcanzar el tiempo límite de 10 segundos bajo carga.
• Cero 4xx y 5xx desde la URL del webhook en funcionamiento normal. Configure alertas para ambos.
• Una tabla de registro de idempotencia que pueda consultar para confirmar que cada webhook se procesó al menos una vez.

Si recibe correos de eventos agotados, las causas raíz más habituales son: (a) la URL del webhook es incorrecta (error tipográfico en el panel), (b) su endpoint exige una autenticación que Certivant no proporciona (la URL debe aceptar POST sin autenticar: la cabecera de firma es la autenticación), (c) su endpoint responde de forma sistemáticamente más lenta que 10 segundos. Investigue cada una.