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 creadasigning_request.sent- Solicitud de firma enviada a los destinatariossigning_request.viewed- El destinatario visualizó el documentosigning_request.completed- Todos los destinatarios terminaron de firmarsigning_request.expired- La solicitud de firma expirósigning_request.cancelled- La solicitud de firma fue canceladasigning_request.updated- Metadatos de la solicitud de firma actualizadossigning_request.deleted- Solicitud de firma eliminada (antes de enviarla)signing_request.certificate.generated- Certificado de firma generadosigning_request.reminder.sent- Recordatorio enviado a los destinatarios
Eventos de destinatario
signing_request.recipient.signed- El destinatario completó la firmasigning_request.recipient.declined- El destinatario rechazó firmarsigning_request.recipient.identity_changed- El destinatario cambió su identidad (nombre, empresa, etc.) durante la firmasigning_request.recipient.email_bounced- Un correo electrónico enviado al destinatario rebotó
Eventos de plantilla
template.updated- Plantilla modificadatemplate.used- Plantilla usada para crear una solicitud de firma
Eventos de sello de organización
organization_seal.created- Nuevo sello creadoorganization_seal.updated- Imagen del sello reemplazada (nueva versión), sello renombrado o marca de predeterminado cambiadaorganization_seal.deleted- Sello revocadoorganization_seal.erased- Linaje de sello revocado borrado permanentemente
Eventos de sello en solicitudes de firma
signing_request.seal.applied- Sello aplicado a un documentosigning_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 creadoworkspace.updated- Espacio de trabajo modificado
Eventos de dominio
domain.verified- Dominio verificado correctamentedomain.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.
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)
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 actualX-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 eliddel 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 firmav1= 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-SignatureyX-Firma-Signature-Oldincluyen cada uno su propiot, así que lee la marca de tiempo del header que estés verificando.
Obtén tu secret de firma
- Ve a tu panel de Firma
- Consulta los detalles del webhook para obtener el secret de firma
- 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 conPOST /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.
- Firma genera un nuevo secret
- Durante 7 días, Firma envía ambas firmas:
X-Firma-Signature(secret nuevo)X-Firma-Signature-Old(secret anterior)
- Después de 7 días, solo se envía
X-Firma-Signature.GET /webhooks/secret-statusoGET /workspaces/{id}/webhooks/secret-statusdevuelvegrace_period_ends_at.
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
- Rota el secret inmediatamente.
- Despliega de inmediato el secret nuevo en tu endpoint.
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-Deliveryy, para los eventos reales, el mismoiddel 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_failuresllega a 50, el webhook se desactiva automáticamente y Firma envía un correo electrónico al propietario de la cuenta. Vuelve a activarlo conPUT /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}/testse 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.
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_atdel 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 conGET /signing-requests/{id}.
Idempotencia
Siempre maneja eventos duplicados usando elid del evento:
Monitorear la salud del webhook
Monitorea la salud de tu webhook consultando los detalles del webhook:consecutive_failures- Contador de fallos usado para la desactivación automática. Vuelve a0después de una entrega correcta.enabled- Indica si el webhook está activo. Se desactiva automáticamente cuandoconsecutive_failuresllega a 50.auto_disabled_at- Momento en el que el webhook se desactivó automáticamente, de lo contrarionull
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}/testomite el interruptor maestro, por lo que puede tener éxito aunque los eventos reales no se disparen. - Revisa
consecutive_failuresen el webhook - si muestra0y 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.
- 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
- 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
- Implementa idempotencia usando el
iddel evento - Almacena los IDs de eventos procesados en tu base de datos
- Revisa
consecutive_failuresy 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-SignaturecomoX-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
iddel evento - Almacenar el secret de firma de forma segura (variable de entorno o gestor de secretos)
- Monitorear la métrica
consecutive_failuresmediante 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
- Crea un webhook mediante la API
- Prueba tu webhook antes de ponerlo en marcha
- Actualiza la configuración del webhook según sea necesario