Webhooks
Un webhook es una URL de tu sistema a la que ValidaFirma avisa cada vez que ocurre algo con un documento. Es la vía principal para enterarte del resultado.
Cómo se configura
Al crear el documento, indicas webhook_url. Debe ser https, en el puerto 443, sin usuario ni clave y hacia una dirección pública; si no, la creación responde WEBHOOK_URL_NO_PERMITIDA. ValidaFirma no sigue redirecciones.
El secreto con el que se firman los avisos está en /panel/integraciones, sección «Webhooks», con los botones «Revelar» y «Copiar». El de prueba empieza con whsec_test_ y el de producción con whsec_live_. El secreto de producción se copia desde el panel a la configuración de tu sistema, y de ahí no sale: ni al código, ni al repositorio, ni a un mensaje.
Los eventos
| Evento | Cuándo ocurre |
|---|---|
documento.completado |
El documento quedó sellado: firmaron todos los firmantes o se cerró con quienes firmaron, al vencer el plazo o porque lo cerraste tú. cierre.marca dice cuál (firmado_por_todos, cerrado_al_vencer o cerrado_por_el_emisor). |
documento.no_emitido |
El documento no llegó a emitirse. |
documento.rechazado |
Un firmante rechazó el documento. |
documento.cancelado |
Se canceló el documento. |
documento.expirado |
Se cumplió el plazo sin que firmaran todos. Llega solo por webhook. |
firmante.rechazado |
Un firmante rechazó y el documento sigue para los demás. |
firmante.firma_tras_rechazo |
Quien había rechazado firmó el documento. |
firmante.bloqueado |
Un firmante quedó bloqueado. |
firmante.identidad_no_coincide |
La identidad verificada no coincide con la esperada. |
firmante.identidad_aprobada |
Una revisión aprobó la identidad. |
firmante.invitacion_no_entregada |
La invitación no llegó a su destino. |
firmante.validacion_contacto_no_lograda |
El firmante no logró validar su contacto. |
Qué trae cada entrega
Cada aviso llega por POST con estas cabeceras:
| Cabecera | Contenido |
|---|---|
X-ValidaFirma-Event |
El nombre del evento. |
X-ValidaFirma-Delivery |
El identificador de esta entrega. |
X-ValidaFirma-Version |
La versión del formato del aviso. |
X-Webhook-Signature |
La firma, con la forma t=<unix>,v1=<hex>. |
El cuerpo es un JSON con evento, timestamp y es_prueba en la raíz; el resto depende del evento.
El PDF firmado no viene en el aviso
El aviso documento.completado no trae el PDF: documento_base64 llega en null. Hay dos caminos para tenerlo, y solo esos:
- Descárgalo desde tu servidor con tu llave. El aviso trae
url_api_descarga, que es la rutaGET /api/fes/documentos/{id}/descargar: llámala desde tu servidor con la cabeceraAuthorization: Bearery tu llave (en una cuenta corporativa, la credencial de máquina), y guarda tu copia en un lugar privado, como lo hacen las recetas. Quien ya integró conX-API-Keypuede seguir con ella: sigue vigente. - Envía a tu usuario
url_validacion, la dirección del portal de ValidaFirma donde ve su documento. El código de verificación puede acompañarla.
url_validacion puede ir a tu usuario, por correo o dentro de su sesión. url_api_descarga, tu llave y tu credencial nunca van a tu usuario ni a un correo, una página, una URL o un log (ver datos).
El aviso trae además url_descarga, que está deprecada: no la uses ni se la des a nadie. Deja de venir 30 días corridos después del aviso por correo. La fecha exacta está en ese aviso y en la documentación del API.
Un cuerpo de documento.completado, abreviado y con valores ficticios:
{
"evento": "documento.completado",
"timestamp": "2026-10-17T14:05:09.000Z",
"webhook_version": "1.0",
"es_prueba": true,
"documento": {
"id": "<identificador del documento>",
"es_prueba": true,
"codigo_verificacion": "<código de verificación>",
"nombre_original": "contrato.pdf",
"estado": "firmado",
"completed_at": "2026-10-17T14:05:08.000Z",
"url_validacion": "<dirección del portal para tu usuario>",
"url_api_descarga": "<dirección de descarga del API, para tu servidor>",
"url_descarga": "<deprecada: no la uses>",
"documento_base64": null,
"incluye_documento": false
},
"firmantes": [
{ "rut": "49999901-1", "estado": "firmado" }
]
}
Cómo se verifica
- Lee el cuerpo crudo, tal como llegó, antes de interpretarlo.
- Arma el texto
<t>.<cuerpo crudo>, con eltde la cabecera. - Calcula el HMAC-SHA256 de ese texto con el secreto del modo del documento.
- Compara el resultado con
v1, en tiempo constante. - Rechaza el aviso si
tse aleja del reloj de tu sistema por más de 300 segundos.
Cuando el secreto se rota, la cabecera trae dos valores v1 y el anterior sigue firmando durante 24 horas: acepta el aviso si cualquiera de los dos coincide.
firma_esperada = hmac_sha256(secreto, t + "." + cuerpo_crudo)
valido = alguna_v1 coincide con firma_esperada (comparación en tiempo constante)
Deduplicación y reintentos
ValidaFirma reintenta un aviso fallido, así que el mismo aviso puede llegar más de una vez. Guarda el valor de X-ValidaFirma-Delivery de cada entrega que procesas y descarta las repetidas. No deduplicas por documento: un mismo documento tiene varios eventos legítimos.
Qué responder
Responde con un código 2xx apenas recibas la entrega, sin hacer trabajo largo antes.
Si tardas más de 30 segundos o respondes otro código, la entrega queda fallida. Se reintenta solo cuando la falla puede ser pasajera:
- un error de red o el plazo de 30 segundos vencido;
- un 5xx;
- un 408, un 425 o un 429.
Cualquier otro 4xx no se reintenta: ValidaFirma lo toma como una respuesta definitiva de tu sistema. Un destino bloqueado o una redirección tampoco se reintentan. Cada aviso se intenta 5 veces en total, con esperas crecientes que parten en 1 segundo.
Probar con el sitio en tu computador
Si el sitio no está publicado en internet, ValidaFirma no puede llamarlo. En modo de prueba, el CLI trae los avisos hasta tu computador y comprueba tu webhook de punta a punta con un solo comando:
validafirma prueba verificar --reenviar-a <dirección local de tu webhook> --crear "<comando que crea un documento de prueba desde tu sistema>"
El comando prueba dos desenlaces, la firma y el rechazo. Por cada uno abre el relay, corre el de --crear con el RUT de prueba de ese desenlace en la variable VALIDAFIRMA_RUT_DE_PRUEBA, sigue los avisos de ese documento hasta su estado final y los reenvía a tu dirección local con los mismos encabezados y la misma firma que la entrega real. Después reenvía el aviso de la firma tal cual, como haría un reintento, y una vez más con la firma alterada. Sale con 0 si cada documento llegó a su desenlace, cada aviso y el repetido recibieron 2xx y el de la firma alterada un 4xx. Si no, sale con 9 y dice qué falló. El resultado queda en .validafirma/verificacion.json.
- El documento lo crea el código de tu sistema con la llave del proyecto. No hace falta que traiga
webhook_url. - El RUT del firmante lo toma de
VALIDAFIRMA_RUT_DE_PRUEBA: así cada documento llega solo a su desenlace (ver prueba). Sin--crear, el comando sigue un solo documento, el que crees tú. - En un WordPress sin enlaces permanentes, la dirección local de una ruta REST es
http://localhost:8080/?rest_route=/<espacio>/<ruta>. - Tu sistema verifica la firma con el secreto de webhooks de prueba que
validafirma webhooks secretosdeja enkeys/.
Para mirar los avisos sin verificar nada, validafirma webhooks escuchar --reenviar-a <dirección local> los reenvía mientras está abierto. Lo que ocurre con el relay cerrado se pierde. El relay solo trae documentos de prueba creados con la llave del proyecto; nunca uno de producción. validafirma webhooks secretos muestra los secretos de la cuenta, el de prueba entero y el de producción solo por su sufijo.
Para tu agente
Verifica la firma con el secreto de prueba mientras pruebas. En producción, el secreto lo pone la persona en la configuración de su sistema; tú nunca lo lees ni lo pegas.