🔄 Mecanismo de Callback para Flujos Asíncronos (Async)

Última actualización Hace 8 meses

¿Qué es un callback?

Un callback es una notificación automática que Zenpli envía a tu sistema cuando un proceso asíncrono (como una decisión de onboarding o la extracción de un documento) ha sido completado. Esto permite a tu backend recibir la respuesta sin necesidad de hacer polling.

¿A qué productos aplica?

Este mecanismo aplica a todos los productos de Zenpli que incluyen flujos asíncronos, como:

  • Onboarding API

  • Lucy KYB API Suite

  • Extraction y análisis de documentos legales

¿Cómo funciona?

  1. Tu sistema registra un endpoint (webhook) que estará escuchando callbacks de Zenpli.

  2. Cuando se completa un flujo async, Zenpli envía una solicitud HTTP POST a ese endpoint.

  3. El cuerpo del mensaje contiene los resultados del proceso (p. ej. la extracción completa de un acta o la decisión de onboarding).

Métodos de autenticación soportados

Método

Nivel de Seguridad

Requiere intercambio de claves

Recomendado para

RSA-256

Muy alto

✅ Sí

Producción y staging

HMAC

Alto

✅ Sí

Producción y staging

API Key

Básico

❌ No*

Desarrollo local / testing

1. 🔐 RSA-256

  • Zenpli firma la solicitud usando una clave privada.

  • Tú verificas la firma con la clave pública de Zenpli.

  • Header esperado: X-Zenpli-Signature (o personalizado terminando en -Signature).

2. 🧪 HMAC-SHA256

  • Zenpli genera la firma usando una clave compartida.

  • Tú recalculas la firma y comparas.

  • Header esperado: X-Zenpli-HMAC-Signature (o personalizado terminando en -HMAC-Signature).

3. 🧾 API Key

  • Zenpli incluye una clave que tú validas directamente.

  • Menor seguridad, útil para ambientes de prueba.

  • Header esperado: Authorization (o personalizado terminando en -Authorization).

Ejemplo de flujo

POST /your/webhook-endpoint 
HTTP/1.1 X-Zenpli-Signature: abc123signature== 
X-Session-Id: 789xyz 
Content-Type: application/json

{ 
"status": "completed", 
"session_id": "789xyz", 
"result": { ... 
} 
}

Consideraciones importantes

  • Tienes un máximo de 10 segundos para responder con un HTTP 200 OK.

  • Si no se recibe una respuesta válida, Zenpli aplicará su política de reintentos.

  • Implementa protección contra replay attacks verificando:

    • Que X-Session-Id no se repita.

    • Que la marca de tiempo esté dentro de una ventana válida.

  • Siempre utiliza HTTPS.