Notificaciones

La API de Kambia puede enviar notificaciones sobre el cambio de estado del contrato digital al webhook del cliente.

Cómo se envía la notificación

Método: POST

Content-Type: application/json

Header de firma: x-kambia-signature — firma HMAC-SHA256 para que el cliente verifique que la notificación es de Kambia (ver más abajo).

Configuración

El cliente debe habilitar un webhook que reciba la siguiente estructura de datos:

Una vez recibida la notificación, el webhook debe responder con un estado HTTP 200 OK. Caso contrario, recibirá reintentos de la misma notificación.

El cliente debe proporcionar a Kambia la URL válida para su registro (signature_webhook).

Estados posibles

status	Descripción
CREATED	Contrato digital creado correctamente.
BOUNCED	Contrato digial rebotó por buzón lleno o correo inválido.
REJECTED	Contrato digital rechazado por firmante.
CANCELED	Contrato digital cancelado por `merchant`.
SIGNED	Contrato digital firmado y disponible para descarga, incluye `document_url`.

Verificación de la firma

Cada notificación incluye el header x-kambia-signature. El cliente debe verificar la autenticidad e integridad del cuerpo así:

Obtener el body del request (string JSON tal como se recibió).

Construir el string a firmar: merchant_id + body (concatenación, sin separador).

Calcular HMAC-SHA256 usando su merchant_secret como clave y el string del paso 2 como mensaje.

Comparar el resultado en hex con el valor del header x-kambia-signature.

Si no coinciden, la notificación no debe considerarse válida.

Pruebas automáticas

Para probar la integración del webhook sin necesidad de completar un contrato real, puedes usar el modo demo: al crear un contrato digital con un title que empiece por ejemplo por DEMO_SIGNED o DEMO_BOUNCED, la API enviará automáticamente la notificación correspondiente a tu signature_webhook ~500 ms después.

Ver detalles en la sección "Modo demo" de Create signature.

Ejemplos

1. CREATED

{
    "status": "CREATED",
    "message": "Signature created successfully",
    "timestamp": "2025-02-12T10:00:00.000Z",
    "signature": {
        "id": "env_abc123xyz"
    }
}

2. BOUNCED

{
    "status": "BOUNCED",
    "message": "Email inbox full",
    "timestamp": "2025-02-12T10:05:00.000Z",
    "signature": {
        "id": "env_abc123xyz",
        "reason": "Mailbox full"
    }
}

3. REJECTED

{
    "status": "REJECTED",
    "message": "Signature rejected by recipient",
    "timestamp": "2025-02-12T11:00:00.000Z",
    "signature": {
        "id": "env_abc123xyz",
        "reason": "Recipient declined"
    }
}

4. CANCELED

{
    "status": "CANCELED",
    "message": "Signature canceled by owner",
    "timestamp": "2025-02-12T11:30:00.000Z",
    "signature": {
        "id": "env_abc123xyz",
        "reason": "Canceled by user"
    }
}

5. SIGNED

Cuando el documento ha sido firmado por todos los destinatarios, se envía SIGNED con document_url para descargar el PDF firmado.

{
    "status": "SIGNED",
    "message": "Signature generated successfully",
    "timestamp": "2025-02-12T15:00:00.000Z",
    "signature": {
        "id": "env_abc123xyz",
        "document_url": "https://..."
    }
}

Cómo se envía la notificación#

Configuración#

Estados posibles#

Verificación de la firma#

Pruebas automáticas#

Ejemplos#

1. CREATED#

2. BOUNCED#

3. REJECTED#

4. CANCELED#

5. SIGNED#