Webhooks del espacio de trabajo: entrega aislada de eventos para cada cliente en tu plataforma

Si estás ejecutando un SaaS multiinquilino en Firma.dev, probablemente ya te hayas topado con este muro antes. Un webhook a nivel de empresa recibe eventos de cada solicitud de firma en cada espacio de trabajo, y tu backend tiene que distribuirlos al cliente adecuado. Funciona bien cuando controlas ambos lados. Se desmorona en el momento en que tus clientes quieren que sus propios endpoints de webhook apunten a sus propios sistemas.

Los Webhooks de Espacio de Trabajo solucionan eso. Ahora cada espacio de trabajo puede definir sus propios endpoints de webhook con secretos de firma independientes, totalmente separados de los webhooks a nivel de empresa. Esta es la pieza que hace que el modelo multitenant de Firma.dev funcione realmente de principio a fin.

El problema multitenant que resuelve esto

Los Espacios de Trabajo de Cliente siempre te han dado espacios segmentados para cada cliente en tu plataforma. Cada espacio de trabajo tiene sus propias plantillas, su propio uso de sobres, su propia clave de API. Separación limpia. Pero hasta ahora, la entrega de webhooks era la excepción. Cada evento se enrutaba a través de un único webhook a nivel de empresa, lo que significaba que tu plataforma siempre hacía de intermediaria para las notificaciones.

Eso está bien para algunas arquitecturas. Para otras, es un factor decisivo. Piensa en una plataforma que permite a sus clientes conectar sus propios CRM, ERP o sistemas de tickets. Cada cliente quiere que los eventos de firma se envíen directamente a su propia pila. O considera un revendedor que ofrece a los clientes finales un aislamiento real en todas sus integraciones. O un equipo de desarrollo que quiere que los espacios de trabajo de staging envíen eventos a un endpoint de pruebas mientras producción los envía al real.

En todos esos casos, el webhook tiene que vivir a nivel de espacio de trabajo o todo el modelo presenta fugas.

Qué hay disponible por espacio de trabajo

Cada espacio de trabajo ahora obtiene el conjunto completo de herramientas de webhooks, limitado a sí mismo:

• CRUD completo sobre endpoints de webhook

• Su propio secreto de firma, con un periodo de gracia de rotación de 7 días cuando lo regeneras

• Entrega de prueba, para que puedas verificar la configuración sin activar eventos reales

• Un registro de eventos por espacio de trabajo

• Un selector "Ignorar webhooks de la empresa" si quieres que los webhooks del espacio de trabajo sustituyan por completo la entrega a nivel de empresa en lugar de ejecutarse junto a ella

Ese último selector importa más de lo que parece. Algunos equipos quieren que se activen tanto los webhooks de empresa como los de espacio de trabajo, porque su plataforma sigue necesitando una vista global de los eventos mientras los clientes obtienen sus propios feeds. Otros equipos quieren un aislamiento limpio en el que los webhooks de espacio de trabajo sean la única fuente de verdad. Puedes elegirlo por espacio de trabajo.

Seguridad: protección SSRF en todas las URL de webhook

Hay algo que merece la pena señalar para los desarrolladores que evalúan esto. Toda la validación de URL de webhook ahora incluye protección SSRF, que bloquea rangos de IP privadas, endpoints de metadatos de la nube e intentos de rebinding de DNS. Cuando permites que tus clientes configuren sus propios endpoints de webhook dentro de los espacios de trabajo que controlan, esto no es opcional. Un cliente podría apuntar accidentalmente (o deliberadamente) un webhook a 169.254.169.254 o a una IP interna, y sin protección SSRF estarías haciendo de proxy de solicitudes desde la infraestructura de Firma hacia lugares a los que nadie debería acceder.

Esto se gestiona en la capa de plataforma, así que no necesitas construir defensas por tu cuenta.

Superficie de la API

Algunos añadidos en la parte de la API:

• Parámetro workspace_id en POST /webhooks y GET /webhooks para que puedas acotar las operaciones de webhook a un espacio de trabajo específico

• Nuevos endpoints para gestionar los secretos de webhook del espacio de trabajo: POST /workspaces/{id}/webhooks/rotate-secret y GET /workspaces/{id}/webhooks/secret-status

• Cinco campos nuevos en la respuesta GET del espacio de trabajo que cubren el estado de la configuración de webhooks

Los detalles completos están en el changelog de la API para la v1.15.0.

Cuándo usar webhooks de espacio de trabajo frente a webhooks de empresa

Modelo mental rápido:

Los webhooks de empresa son para tu plataforma. Cualquier cosa que tu aplicación principal necesite conocer, a través de cada cliente, debería pasar por la entrega a nivel de empresa. Eventos de facturación, registro de cumplimiento, analítica, flujos de trabajo internos.

Los webhooks de espacio de trabajo son para tus clientes. Cualquier cosa a la que los sistemas de un cliente específico tengan que reaccionar debería pasar por la entrega a nivel de espacio de trabajo. Actualizaciones de CRM, notificaciones específicas del cliente, integraciones de terceros que hayan configurado ellos mismos.

Ambos pueden coexistir en el mismo espacio de trabajo, o puedes excluir un espacio de trabajo de los webhooks de empresa por completo. Para la mayoría de las plataformas multitenant, el patrón correcto es usar webhooks de empresa para eventos críticos de la plataforma más webhooks de espacio de trabajo que tus clientes configuran a través de tu interfaz.

Empezar

Si ya estás usando Espacios de Trabajo de Cliente, puedes empezar a añadir webhooks de espacio de trabajo hoy mismo. Las integraciones existentes de webhooks a nivel de empresa siguen funcionando exactamente igual que antes. Esto es puramente aditivo.

Empieza gratis con Firma.dev, no se requiere tarjeta de crédito. 25 sobres gratis, sin contratos, sin mínimos, y el conjunto completo de herramientas multitenant, incluidos Espacios de Trabajo de Cliente y Webhooks de Espacio de Trabajo desde el primer día.