Saltar al contenido principal
Firma envía eventos de webhook para notificar a tu aplicación sobre cambios en el ciclo de vida de firma, finalizaciones de documentos y actividades del espacio de trabajo. Los webhooks permiten integraciones en tiempo real sin necesidad de polling.

Casos de uso comunes

  • Enviar notificaciones internas cuando se firman documentos
  • Actualizar tu base de datos cuando se completan solicitudes de firma
  • Activar flujos de trabajo posteriores (facturación, aprovisionamiento, etc.)
  • Rastrear cambios de estado de las solicitudes de firma en tiempo real

Tipos de eventos

Firma envía los siguientes tipos de eventos:

Eventos de solicitud de firma

  • signing_request.created - Nueva solicitud de firma creada
  • signing_request.sent - Solicitud de firma enviada a los destinatarios
  • signing_request.viewed - El destinatario visualizó el documento
  • signing_request.completed - Todos los destinatarios terminaron de firmar
  • signing_request.expired - La solicitud de firma expiró
  • signing_request.cancelled - La solicitud de firma fue cancelada
  • signing_request.updated - Metadatos de la solicitud de firma actualizados
  • signing_request.deleted - Solicitud de firma eliminada (antes de enviarla)
  • signing_request.certificate.generated - Certificado de firma generado
  • signing_request.reminder.sent - Recordatorio enviado a los destinatarios

Eventos de destinatario

  • signing_request.recipient.signed - El destinatario completó la firma
  • signing_request.recipient.declined - El destinatario rechazó firmar
  • signing_request.recipient.identity_changed - El destinatario cambió su identidad (nombre, empresa, etc.) durante la firma
  • signing_request.recipient.email_bounced - Un correo electrónico enviado al destinatario rebotó

Eventos de plantilla

  • template.updated - Plantilla modificada
  • template.used - Plantilla usada para crear una solicitud de firma

Eventos de sello de organización

  • organization_seal.created - Nuevo sello creado
  • organization_seal.updated - Imagen del sello reemplazada (nueva versión), sello renombrado o marca de predeterminado cambiada
  • organization_seal.deleted - Sello revocado
  • organization_seal.erased - Linaje de sello revocado borrado permanentemente

Eventos de sello en solicitudes de firma

  • signing_request.seal.applied - Sello aplicado a un documento
  • signing_request.seal.paused - Participante de sello pausado (sello revocado con detención de pendientes, o discrepancia de integridad)
  • signing_request.seal.swapped - Participante de sello pausado intercambiado por otro sello

Eventos de espacio de trabajo

  • workspace.created - Nuevo espacio de trabajo creado
  • workspace.updated - Espacio de trabajo modificado

Eventos de dominio

  • domain.verified - Dominio verificado correctamente
  • domain.verification.failed - Falló la verificación del dominio

Dos niveles de habilitación

La entrega de webhooks requiere que ambos interruptores estén activados: un interruptor por webhook y un interruptor maestro a nivel de cuenta. Los dos son independientes, por lo que un webhook puede crearse y habilitarse correctamente sin llegar a disparar un solo evento. Al menos un alcance (empresa o espacio de trabajo) debe tener su interruptor maestro activado para que se entregue cualquier webhook de ese alcance. Activar el interruptor maestro del espacio de trabajo también genera un secret de firma para ese espacio de trabajo si aún no existe uno.
POST /webhooks/{id}/test omite el interruptor maestro. Una entrega de prueba puede tener éxito incluso cuando el interruptor maestro está desactivado y los eventos reales no se están entregando - una prueba exitosa no confirma que los eventos reales se disparen.
Cuando el interruptor maestro está desactivado, Firma omite el evento antes de registrar un intento de entrega. consecutive_failures permanece en 0 y el webhook no muestra historial de fallos, aunque no se esté entregando nada - no hay ningún error que te alerte.

Permisos

Activar o desactivar el interruptor maestro a nivel de empresa requiere acceso de propietario o administrador de la empresa; los miembros de solo lectura no pueden habilitarlo ni deshabilitarlo. Intentar cambiarlo sin permisos suficientes devuelve un error de permisos.

Crear un webhook

Crea webhooks a través de la API o del panel:
Tu URL de webhook debe usar HTTPS y responder en un plazo de 5 segundos. Usa POST /webhooks/{id}/test después de la creación para verificar que tu endpoint está recibiendo eventos correctamente.

Estructura del payload del webhook

El id de un destinatario (en recipient o recipients) es la clave de acceso de firma de ese destinatario (/signing/{id}): trátala como un secreto. Todos los eventos comparten el sobre id, type, created_at, company_id, workspace_id y data; este ejemplo corresponde a un evento signing_request.completed:
Las entregas de prueba de POST /webhooks/{id}/test usan una estructura diferente: type (webhook.test), webhook_id, timestamp y data. No tienen id, así que omite para ellas la comprobación de idempotencia.

Seguridad: Verificación de firma (Obligatorio)

Siempre verifica las firmas de los webhooks para prevenir ataques de suplantación. No proceses webhooks sin verificación de firma.
Firma firma todas las solicitudes de webhook usando HMAC SHA-256. Tu endpoint de webhook recibe estos headers:
  • X-Firma-Signature - Firma HMAC usando el secret de firma actual
  • X-Firma-Signature-Old - Firma HMAC usando el secret anterior (durante el período de gracia de rotación de 7 días)
  • X-Firma-Event - Tipo de evento (por ejemplo, signing_request.completed)
  • X-Firma-Delivery - ID de la entrega de este evento a tu endpoint. Se mantiene igual en cada reintento, automático o manual. Usa el id del payload para identificar el evento.

Formato de la firma

Firma usa un header de firma con marca de tiempo:
  • Header: X-Firma-Signature: t=1707500000,v1=abc123def456...
  • t = Marca de tiempo Unix (segundos) cuando se generó la firma
  • v1 = Digest hexadecimal HMAC-SHA256
  • Formato del payload firmado: {timestamp}.{json_body}
  • La clave HMAC es tu secret de firma exactamente como aparece en el panel (64 caracteres). No lo decodifiques como hexadecimal.
  • X-Firma-Signature y X-Firma-Signature-Old incluyen cada uno su propio t, así que lee la marca de tiempo del header que estés verificando.
Ejemplo:

Obtén tu secret de firma

  1. Ve a tu panel de Firma
  2. Consulta los detalles del webhook para obtener el secret de firma
  3. Almacena el secret de forma segura (variable de entorno o gestor de secretos)

Ejemplo de verificación - Node.js (Express)

Ejemplo de verificación - Python (Flask)

Manejo de rotación de secrets

Rota tu secret de firma de webhooks desde el panel, o con POST /webhooks/rotate-secret para los webhooks de empresa o POST /workspaces/{id}/webhooks/rotate-secret para los webhooks de espacio de trabajo. A través de la API, puedes rotar un secret una vez por hora. Los webhooks de un espacio de trabajo se firman con el secret propio de ese espacio de trabajo, no con el secret de la empresa.
  1. Firma genera un nuevo secret
  2. Durante 7 días, Firma envía ambas firmas:
  • X-Firma-Signature (secret nuevo)
  • X-Firma-Signature-Old (secret anterior)
  1. Después de 7 días, solo se envía X-Firma-Signature. GET /webhooks/secret-status o GET /workspaces/{id}/webhooks/secret-status devuelve grace_period_ends_at.
Firma solo conserva un secret anterior. Si vuelves a rotar dentro de los 7 días, se reemplaza el secret anterior y un endpoint que aún conserva el secret de antes de la primera rotación deja de verificar las entregas de inmediato. Despliega cada secret nuevo antes de volver a rotar.
Implementación: Verifica X-Firma-Signature con el secret configurado en tu endpoint. Si esa verificación falla, verifica X-Firma-Signature-Old con el mismo secret. Hasta que despliegues el secret nuevo, el secret configurado es el anterior, que es con el que se firma X-Firma-Signature-Old. Después de desplegarlo, X-Firma-Signature coincide. Despliega el secret nuevo dentro de los 7 días y configura un solo secret a la vez: un endpoint que acepta ambos secrets sigue confiando en el anterior.

Si un secret puede estar comprometido

  1. Rota el secret inmediatamente.
  2. Despliega de inmediato el secret nuevo en tu endpoint.
A partir de ese momento, una solicitud firmada con el secret anterior falla en ambas comprobaciones de tu endpoint, incluso mientras Firma sigue enviando X-Firma-Signature-Old. De este modo, el solapamiento de 7 días no prolonga la confianza en el secret anterior.

Comportamiento de reintentos

Firma no sigue las redirecciones HTTP al entregar webhooks. Registra la URL exacta que sirve tu servidor, incluidos el esquema, el nombre de host, la ruta y la presencia o ausencia de la barra diagonal final. Firma reintenta automáticamente las entregas de webhooks fallidas:
  • Intentos: Hasta 3 por evento: inmediatamente, luego al menos 5 minutos después del primer fallo y después al menos 1 hora tras el segundo fallo. Los reintentos se ejecutan en un ciclo de 5 minutos, así que espera aproximadamente de 5 a 10 minutos y de 60 a 65 minutos, o más cuando haya muchos reintentos en cola.
  • Tiempo de espera: Tu endpoint debe responder en un plazo de 5 segundos
  • Éxito: Cualquier código de estado 2xx indica éxito. Las redirecciones cuentan como fallos.
  • Mismo evento, firma nueva: Cada intento incluye el mismo X-Firma-Delivery y, para los eventos reales, el mismo id del payload, y se vuelve a firmar con una marca de tiempo nueva. El orden de las claves JSON del cuerpo de un reintento puede ser distinto al del primer intento, así que verifica siempre el cuerpo sin procesar exactamente como se recibió.
  • Desactivación automática: Cuando consecutive_failures llega a 50, el webhook se desactiva automáticamente y Firma envía un correo electrónico al propietario de la cuenta. Vuelve a activarlo con PUT /webhooks/{id} ("enabled": true) o en el panel.
  • Después del último intento: Un evento que falla en los 3 intentos no se vuelve a intentar automáticamente. Un administrador puede reintentarlo desde el registro de eventos del webhook en el panel.
  • Sin reintentos: Las entregas de prueba de POST /webhooks/{id}/test se envían una sola vez. Una entrega a una URL que no supera la comprobación de dirección que Firma realiza en el momento de la entrega (por ejemplo, una URL que se resuelve a una dirección privada o de loopback) falla sin reintento.
Mejor práctica: Responde con 200 inmediatamente y luego procesa los eventos de forma asíncrona (cola, tarea en segundo plano, etc.) para evitar tiempos de espera agotados.

Límites de entrega

Los webhooks son notificaciones, no un registro completo de eventos:
  • Los eventos no se entregan en un orden garantizado y un evento reintentado puede llegar después de uno posterior. Usa el campo created_at del payload como referencia y obtén el estado actual de la API.
  • Los eventos generados mientras un webhook o su interruptor maestro está desactivado no se almacenan ni se entregan más tarde. Volver a activar un webhook no los reproduce.
  • Cuando un webhook ya tiene 100 eventos de los últimos 60 segundos, los nuevos eventos destinados a él se omiten y nunca se entregan.
  • No hay ninguna API para listar o reproducir eventos. Para conciliar después de una interrupción, lista las solicitudes de firma con GET /signing-requests (por ejemplo, status=finished&sort_by=finished_on&sort_order=desc) y obtén cada una con GET /signing-requests/{id}.

Idempotencia

Siempre maneja eventos duplicados usando el id del evento:

Monitorear la salud del webhook

Monitorea la salud de tu webhook consultando los detalles del webhook:
La respuesta incluye:
  • consecutive_failures - Contador de fallos usado para la desactivación automática. Vuelve a 0 después de una entrega correcta.
  • enabled - Indica si el webhook está activo. Se desactiva automáticamente cuando consecutive_failures llega a 50.
  • auto_disabled_at - Momento en el que el webhook se desactivó automáticamente, de lo contrario null
Límite de tasa: Cada endpoint de /webhooks permite 60 solicitudes por minuto por clave API. POST /webhooks/{id}/test permite 10 solicitudes por minuto.

Solución de problemas

Problemas comunes

Los webhooks están configurados pero los eventos no se disparan Esta es la causa más común de los reportes de “mi webhook no funciona”. La configuración por webhook puede ser completamente correcta mientras el interruptor maestro a nivel de cuenta está desactivado, lo que omite silenciosamente todos los eventos.
  • Confirma que el interruptor maestro está activado para el alcance correcto: los webhooks a nivel de empresa necesitan el interruptor de la empresa activado, los webhooks a nivel de espacio de trabajo necesitan el interruptor de ese espacio de trabajo activado.
  • No confíes en una prueba exitosa como prueba definitiva - POST /webhooks/{id}/test omite el interruptor maestro, por lo que puede tener éxito aunque los eventos reales no se disparen.
  • Revisa consecutive_failures en el webhook - si muestra 0 y no aparecen eventos, eso también apunta al interruptor maestro, ya que los eventos omitidos nunca se registran como intentos de entrega fallidos.
  • Si no encuentras o no puedes cambiar el interruptor maestro, es posible que no tengas permisos de propietario o administrador en la empresa; pide a un propietario o administrador que lo active desde Configuración > Webhooks.
401 Unauthorized / Firma inválida
  • Verifica que estás usando el secret de firma correcto
  • Comprueba que estás hasheando el cuerpo de la solicitud sin procesar (no el JSON parseado)
  • Asegúrate de estar usando HMAC SHA-256 y no otro algoritmo de hash
Tiempos de espera agotados / errores 504
  • Responde con 200 inmediatamente y procesa de forma asíncrona
  • Comprueba que tu endpoint responde en un plazo de 5 segundos
  • Usa tareas en segundo plano/colas para el procesamiento pesado
Eventos duplicados
  • Implementa idempotencia usando el id del evento
  • Almacena los IDs de eventos procesados en tu base de datos
Webhook desactivado automáticamente
  • Revisa consecutive_failures y los eventos recientes en el registro de eventos del webhook del panel
  • Corrige los problemas del endpoint y luego vuelve a activar el webhook mediante la API o el panel

Probar webhooks localmente

Usa un servicio de túnel como ngrok para el desarrollo local:

Lista de verificación para producción

  • Verificar las firmas HMAC en todas las solicitudes de webhook
  • Manejar la rotación de firmas (comprobar tanto X-Firma-Signature como X-Firma-Signature-Old)
  • Responder con 200 en un plazo de 5 segundos
  • Procesar eventos de forma asíncrona (colas/tareas en segundo plano)
  • Implementar idempotencia usando el id del evento
  • Almacenar el secret de firma de forma segura (variable de entorno o gestor de secretos)
  • Monitorear la métrica consecutive_failures mediante el endpoint GET de webhook
  • Configurar alertas para fallos de webhooks
  • Registrar todos los eventos de webhook para depuración
  • Probar con todos los tipos de eventos suscritos
  • Mantente dentro de los límites de tasa (Consulta la Guía de Límites de Tasa)

Próximos pasos