Webhooks

Qué hace

Un webhook es una URL a la que enviamos una petición POST cada vez que ocurre algo en su organización de Certivant. En lugar de consultar nuestra API para saber si hay cambios («¿ha terminado ya la verificación?»), nos da una URL y le avisamos en el momento en que ocurre. Los eventos de webhook sirven para mantener sincronizados sus sistemas: flujos de alta de clientes, bases de datos de riesgo AML, etiquetas de CRM, paneles internos de cumplimiento normativo.

Dónde está

KYC → Webhooks en la barra lateral izquierda. (Los eventos de KYB se envían a los mismos puntos de conexión de webhook: no existe una configuración de webhook separada para KYB.)

Configuración

const sig = req.headers["x-certivant-signature"];
const expected = hmac("sha256", secret).update(rawBody).digest("hex");
if (!timingSafeEqual(sig, expected)) return 401;

Tipos de evento

La lista completa y las cargas útiles JSON están documentadas en KYC → Desarrollador → Eventos de webhook.

Estructura de la carga útil

Todos los eventos tienen el mismo sobre:

{
  "id": "evt_2k3f9a...",
  "type": "kyc.request.approved",
  "createdAt": "2026-05-27T14:30:00Z",
  "organizationId": "org_abc123",
  "data": { /* event-specific payload */ }
}

El campo data varía según el tipo de evento. Por ejemplo, kyc.request.approved envía:

{
  "request": { "id": "kyr_...", "status": "APPROVED", "type": "INDIVIDUAL", ... },
  "applicant": { "id": "ka_...", "fullName": "Jane Doe", "email": "...", ... },
  "decision": { "by": "auto" | "manual", "reviewerId": "user_..." | null, "note": "..." | null },
  "policy": {
    "id": "pol_..." | null,
    "name": "default-kyc-policy",
    "version": 3 | null,
    "isDefault": true,
    "decision": "approve" | "reject" | "escalate" | "live_verification",
    "rulesFired": ["tier1-disqualified", "approve-by-score"],
    "reason": "High-risk country",
    "liveVerificationRequired": true
  }
}

El bloque policy (en kyc.request.approved / rejected / escalated) indica qué política de riesgo decidió la solicitud y qué reglas se activaron. isDefault: true significa que se ejecutó la política predeterminada de Certivant (id/version corresponden a la fila de la política predeterminada de su organización, o son null si aún no se ha creado); una política personalizada informa de su id, name y version almacenados. rulesFired enumera los ids de las reglas que coincidieron, en orden de evaluación: use estos datos para bifurcar sus automatizaciones posteriores. reason es el motivo de la regla ganadora, cuando la regla lo define. decision: "live_verification" (con liveVerificationRequired: true, en kyc.request.escalated) significa que la política necesita una verificación de identidad en vivo antes de una decisión final: la solicitud espera en revisión manual hasta que la llamada decida. Consulte Diseñar una política de riesgo.

Si opera en modo socio (una organización que atiende a muchos clientes finales), cada sobre de evento incluye también subTenantName y subTenantExternalId: las etiquetas definidas en la solicitud cuando se creó mediante la API, para que su manejador pueda enrutar el resultado al cliente final correcto. Consulte la referencia de webhooks para desarrolladores para ver la ubicación exacta de cada campo.

Reintentos

Si su punto de conexión devuelve un código distinto de 2xx (o no responde a tiempo), reintentamos con retroceso exponencial:

attempt 1: immediately
attempt 2: 30 seconds later
attempt 3: 5 minutes later
attempt 4: 30 minutes later
attempt 5: 2 hours later
attempt 6: 6 hours later
attempt 7: 24 hours later

Tras 7 intentos fallidos, marcamos el evento como permanently_failed (fallo permanente) y dejamos de reintentarlo. Los eventos fallidos aparecen en el panel de webhooks con su último error; puede volver a enviar manualmente cualquiera de ellos con Reintentar.

Varios puntos de conexión

Puede registrar varios puntos de conexión (por ejemplo, uno para su CRM y otro para su almacén de datos AML). Cada uno puede suscribirse a un conjunto distinto de tipos de evento. Cada punto de conexión tiene su propio secreto de firma: rotar uno no rompe los demás.

Webhooks por formulario

El webhook de toda la organización se dispara para cada evento relevante. Los formularios públicos pueden tener ADEMÁS una URL de webhook por formulario en sus ajustes, útil cuando un formulario alimenta un sistema independiente. Los webhooks por formulario se ejecutan además de los de la organización.

La página KYC → Webhooks muestra ahora ambos en un solo lugar: la URL de webhook de la organización en la parte superior, y una fila para la URL de webhook de cada formulario debajo, para que vea todos los destinos de entrega sin buscar en los ajustes de cada formulario.

El panel de webhooks

KYC → Webhooks enumera cada punto de conexión con:

• URL del punto de conexión y nombre descriptivo.
• Estado: activo / en pausa / con fallos.
• Última entrega: cuándo se envió la última petición POST.
• Tasa de éxito: % de intentos que devolvieron 2xx en los últimos 7 días.
• Entregas recientes: tabla con los eventos recientes, su código de estado, la latencia y el cuerpo de la respuesta.

Pause un punto de conexión para detener las entregas sin perder la configuración.

Solución de problemas

Mi punto de conexión recibe demasiadas peticiones

Los puntos de conexión reciben una llamada por evento, pero una organización muy activa puede generar decenas por minuto. Haga que su punto de conexión sea asíncrono: acepte el POST, responda 2xx de inmediato y procese la carga útil fuera del ciclo de vida de la petición. Si necesita que reduzcamos el ritmo, configure la opción Máximo de entregas simultáneas del punto de conexión.

La verificación de firma falla constantemente

Tres causas habituales:

1. Analizar el cuerpo antes de verificar la firma. Use los bytes en bruto. Si usa Express + body-parser, configure bodyParser.raw({ type: 'application/json' }) específicamente para la ruta del webhook.
2. Secreto incorrecto. Rote el secreto y vuelva a pegarlo.
3. Modificar el cuerpo en un middleware (gzip, BOM, codificación). La firma se calcula sobre los bytes exactos que enviamos.

Los eventos parecen duplicados

Son reintentos por respuestas lentas. Use event.id como clave de idempotencia.

El orden de los eventos es importante, pero los recibo desordenados

No garantizamos un orden estricto entre tipos de evento. Para el orden por solicitante, use el campo createdAt del evento: el orden dentro del ciclo de vida de un solicitante concreto es monótono.

Relacionado

• Registro de auditoría: cada envío de webhook también queda registrado aquí.
• Desarrollador (claves de API): si quiere consultar el estado mediante REST en lugar de recibir envíos.
• Formularios: vista previa y publicación: webhooks por formulario.