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

Si estás ejecutando un SaaS multi-inquilino en Firma.dev, es probable que ya te hayas topado con este muro antes. Un webhook a nivel de empresa recibe eventos para cada solicitud de firma en todos los espacios de trabajo, y tu backend tiene que distribuirlos al cliente correcto. Funciona bien cuando controlas ambos lados. Se desmorona en el momento en que tus clientes quieren sus propios endpoints de webhook apuntando 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 de multi-inquilino de Firma.dev realmente funcione de extremo a extremo.

El problema de multi-inquilino que esto resuelve

Los Espacios de Trabajo de Cliente siempre te han proporcionado espacios particionados para cada cliente en tu plataforma. Cada espacio de trabajo tiene sus propias plantillas, su propio uso de sobres, su propia clave API. Una 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 era el intermediario para las notificaciones.

Eso está bien para algunas arquitecturas. Pero es un obstáculo insalvable para otras. 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 tecnológica. O considera a un distribuidor 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 prueba envíen eventos a un endpoint de prueba mientras producción lo hace al real.

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

Qué está disponible por espacio de trabajo

Cada espacio de trabajo cuenta ahora con el conjunto de herramientas de webhook completo, limitado a sí mismo:

• CRUD completo en los endpoints de webhook

• Su propio secreto de firma, con un periodo de gracia de rotación de 7 días al regenerarlo

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

• Un registro de eventos por espacio de trabajo

• Una opción para "Ignorar Webhooks de Empresa" si deseas que los webhooks de espacio de trabajo reemplacen por completo la entrega a nivel de empresa en lugar de ejecutarse de forma conjunta

Esa última opción 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 sus plataformas siguen necesitando una visión global de los eventos mientras que los clientes obtienen sus propios feeds. Otros equipos quieren un aislamiento limpio donde los webhooks del espacio de trabajo sean la única fuente de verdad. Puedes elegir por espacio de trabajo.

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

Algo que vale la pena destacar para los desarrolladores que estén evaluando esto. Toda la validación de URL de webhooks ahora incluye protección SSRF, que bloquea rangos de IP privadas, endpoints de metadatos en la nube e intentos de reasociación 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, de forma accidental (o deliberada), apuntar un webhook a 169.254.169.254 o a una IP interna, y sin protección SSRF estarías actuando como proxy de solicitudes desde la infraestructura de Firma hacia lugares a los que nadie debería acceder.

Esto se gestiona en la capa de la plataforma, por lo que no necesitas compilar defensas por tu cuenta.

Superficie de la API

Algunas adiciones en el lado de la API:

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

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

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

Todos los detalles están en el registro de cambios de la API para v1.15.0.

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

Un modelo mental rápido:

Los webhooks de empresa son para tu plataforma. Todo aquello sobre lo que tu aplicación principal deba estar informada, en relación con cada cliente, debe fluir a través de la entrega a nivel de empresa. Eventos de facturación, registro de cumplimiento, analíticas, flujos de trabajo internos.

Los webhooks de espacio de trabajo son para tus clientes. Todo aquello a lo que los sistemas de un cliente específico deban reaccionar debe fluir a través de la entrega a nivel de espacio de trabajo. Actualizaciones de CRM, notificaciones específicas del cliente, integraciones de terceros que ellos mismos hayan configurado.

Ambos pueden coexistir en el mismo espacio de trabajo, o puedes excluir por completo un espacio de trabajo de los webhooks de empresa. Para la mayoría de las plataformas multi-inquilino, el patrón correcto consiste en usar webhooks de empresa para eventos críticos de la plataforma y webhooks de espacio de trabajo que tus clientes configuren a través de tu interfaz de usuario.

Primeros pasos

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

Comienza a utilizar Firma.dev de forma gratuita, sin necesidad de tarjeta de crédito. Sin contratos ni mínimos, y con el conjunto completo de herramientas multi-inquilino, incluidos los Espacios de Trabajo de Cliente y los Webhooks de Espacio de Trabajo, desde el primer día.