Webhooks

Webhooks

Puedes especificar un webhook para recibir notificaciones en tu servidor cuando un documento ha sido firmado, revisarlo, y continuar con tu proceso.

Para especificar un webhook, inicia sesión en tu cuenta de desarrollador en https://acertia.mx/developers/login. La URL que proporciones debe aceptar solicitudes HTTP POST con un JSON Content Type (application/json).

Cada vez que se firme un documento que tu generaste, Acertia hará un POST a tu webhook con esta información:

{
    //el id de la notificación, puedes usar este id para solicitar
    //más información sobre este documento
    notification_id: 32,
    //el título del documento que fue firmado
    document_title: 'terms_of_service.pdf',
    //un id único para el documento (tal como se encuentra en la url)
    //url: https://Acertia.com/pdf/94a9398d-e0b6-40cf-9334-5f7f24fb883s/
    Acertia_id: '94a9398d-e0b6-40cf-9334-5f7f24fb883s',
    //descripción del evento
    text: 'Document just signed',
    //tipo de notificación, existen tres tipos posibles:
    //1. original_signed: un usuario ha firmado este documento
    //2. universal_signed: la firma ha sido encapsulada
    //3. document_completed: se han firmado todos los stickers
    notification_type: 'original_signed',
    //el correo del firmante
    signer_email:'[email protected]',
    //fingerprint del certificado del firmante
    signer_fingerprint: 'ae5e5f0846658e05d6afr2fad84f10ba5fb71d328'
    // informacion adicional del firmante
    signer_data: {}
}

Si la cuenta de tu organización tiene activados los sellos NOM151 de manera automática, además de las anteriores recibirás otras dos notificaciones

{
    //1. original_nom151_stamped: se ha realizado el sello nom151 
    //   sobre el documento original
    //2. universal_nom151_stamped: se ha realizado el sello nom151
    //   sobre el documento universal
    notification_type: 'original_nom151_stamped',
    meta: {
        hash: 'hash del documento con el que se generó el sello',
        tsa: 'nombre de la autoridad que firmó el sello',
        policy: 'policy id de la autoridad',
        genTime: 'fecha de generación del sello'
    }
}

Confirmación de Webhook

Acertia espera recibir un código HTTP 200 como respuesta a la notificación. Si no lo recibe, asume que hay un problema y se comportará de la siguiente manera:

1. URL inválida: si el webhook es una URL inválida, no volverá a intentar

2. Si no se obtiene respuesta de una URL válida: Acertia volverá a intentar utilizando exponential backoff. Esto quiere decir que programará su ejecución de acuerdo a la siguiente fórmula:

10 segundos + min((2 ^ intentos), 600) + Random(0-1)ms

Por lo que el tiempo irá incrementando entre cada intento hasta llegar a un máximo de 600 segundos (10 minutos) y 30 intentos.

Consultas

Con el notification_id puedes solicitar más detalles sobre un documento. La solicitud tiene que contener la siguiente información:

{
    //el id de la notificación que recibiste
    notification_id: 32
    //la acción que quieres realizar
    //(ve más abajo para más información)
    action: 'download_document'
}

Acciones disponibles

Actualmente hay cuatro acciones disponibles

1.download_document. Descarga un JSON con el documento con las firmas encapsuladas

const response = await services.getData({
    notification_id: 5,
    action: 'download_document'
})

Esto regresará un JSON con la siguiente información:

{
    //nombre del documento
    name: "default.pdf",
    //número actual de firmas en el documento
    signatures_count: 1,
    //PDF codificado en base64
    data:"base64data"
}

2. download_document_bytes. Descarga el documento con las firmas encapsuladas

3. download_original_document. Descarga un JSON con el documento con las firmas originales.

4. download_original_bytes. Descarga el documento con las firmas originales.