manyao — Webhook de Sesiones

🔔 Webhook de Sesiones

Recibe notificaciones automáticas cuando una sesión de verificación de identidad cambia de estado. Ideal para login biométrico, verificación de edad o cualquier flujo que requiera validación de identidad en tiempo real.

MétodoPOST

FormatoJSON

Latencia< 2 segundos

📡Cómo funciona

sequenceDiagram participant B as Tu Backend participant A as API Manyao participant U as Usuario B->>A: POST /sessions (con callback_url + metadata) A-->>B: session_id + qr_url B-->>U: Muestra QR en pantalla U->>A: Escanea QR con su celular A->>A: Validación biométrica + prueba de vida alt Verificación exitosa A->>B: POST callback_url { event: "session.verified" } B-->>U: Notifica al frontend → Login aprobado else Verificación fallida A->>B: POST callback_url { event: "session.failed" } B-->>U: Notifica al frontend → Login denegado end

⚙️Cómo Activarcallback_url

curl -X POST 'https://api.manyao.pe/v1/sessions' \
  -H 'Authorization: Bearer {{token}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "doc_type": "dni-pe",
    "doc_number": "12345678",
    "callback_url": "https://tu-app.com/webhooks/manyao-session",
    "metadata": {"ref": "login-user-456"}
  }'

📋Eventos

Evento	Descripción	Cuándo se envía
session.verified	Identidad verificada exitosamente	Después de la validación biométrica + prueba de vida
session.failed	Verificación fallida	Cuando la persona no pasa la validación
session.expired	Sesión expirada	Al cumplirse el tiempo de vigencia sin verificar

📦Payloads del Webhook

session.verified

{
  "event": "session.verified",
  "session_id": "s1b2c3d4-e5f6-...",
  "doc_type": "dni-pe",
  "doc_number": "12345678",
  "verified_name": "JUAN PEREZ GARCIA",
  "verified_data": {
    "names": "JUAN",
    "paternal": "PEREZ",
    "maternal": "GARCIA"
  },
  "score": 0.98,
  "liveness": { "passed": true, "score": 0.99 },
  "metadata": {"ref": "login-user-456"},
  "verified_at": "2026-03-22T10:05:00",
  "timestamp": "2026-03-22T10:05:01"
}

session.failed

{
  "event": "session.failed",
  "session_id": "s1b2c3d4-e5f6-...",
  "doc_type": "dni-pe",
  "reason": "liveness_failed",
  "metadata": {"ref": "login-user-456"},
  "timestamp": "2026-03-22T10:05:01"
}

🔍Campos del payload session.verified

Campo	Tipo	Descripción
event	string	Siempre `session.verified`
session_id	string	UUID de la sesión
doc_type	string	`dni-pe`, `dni-pa`, `ci-pe`
doc_number	string	Número de documento verificado
verified_name	string	Nombre completo extraído del documento
verified_data.names	string	Nombres del titular
verified_data.paternal	string	Apellido paterno
verified_data.maternal	string	Apellido materno
score	float	Score de coincidencia biométrica (0 a 1)
liveness.passed	boolean	Si pasó la prueba de vida
liveness.score	float	Score de prueba de vida (0 a 1)
metadata	object	Datos que enviaste al crear la sesión
verified_at	datetime	Timestamp de verificación
timestamp	datetime	Timestamp del envío del webhook

💻Ejemplo — Login Biométrico (Node.js)

app.post('/webhooks/manyao-session', async (req, res) => {
  const { event, session_id, doc_number, verified_name, metadata } = req.body;

  if (event === 'session.verified') {
    // Buscar usuario por DNI
    const user = await User.findByDni(doc_number);
    if (user) {
      const loginToken = generateLoginToken(user.id);
      // Notificar al frontend via WebSocket/SSE usando el ref del metadata
      notifyFrontend(metadata.ref, { authenticated: true, token: loginToken });
    }
  }

  if (event === 'session.failed') {
    notifyFrontend(metadata.ref, {
      authenticated: false,
      reason: req.body.reason
    });
  }

  res.status(200).json({ received: true });
});

🐘Ejemplo — Login Biométrico (PHP)

// webhooks/manyao-session.php
$payload = json_decode(file_get_contents('php://input'), true);
$event = $payload['event'] ?? '';

if ($event === 'session.verified') {
    $user = findUserByDni($payload['doc_number']);
    if ($user) {
        $token = generateLoginToken($user['id']);
        notifyFrontend($payload['metadata']['ref'], [
            'authenticated' => true,
            'token' => $token,
            'name' => $payload['verified_name']
        ]);
    }
}

if ($event === 'session.failed') {
    notifyFrontend($payload['metadata']['ref'], [
        'authenticated' => false,
        'reason' => $payload['reason']
    ]);
}

http_response_code(200);
echo json_encode(['received' => true]);

manyao.pe — Firma digital con validación biométrica