Webhooks do Workspace: entrega isolada de eventos para cada cliente na sua plataforma

Se está a executar um SaaS multi-inquilino na Firma.dev, provavelmente já deparou com este obstáculo antes. Um webhook ao nível da empresa recebe eventos para cada pedido de assinatura em todos os espaços de trabalho, e o seu backend tem de os distribuir ao cliente certo. Funciona bem quando controla ambos os lados. Desmorona-se no momento em que os seus clientes querem os seus próprios endpoints de webhook apontados para os seus próprios sistemas.

Os Webhooks de Espaço de Trabalho resolvem isso. Cada espaço de trabalho pode agora definir os seus próprios endpoints de webhook com segredos de assinatura independentes, totalmente separados dos webhooks ao nível da empresa. Esta é a peça que faz o modelo multi-inquilino da Firma.dev funcionar realmente de ponta a ponta.

O problema multi-inquilino que isto resolve

Os Espaços de Trabalho do Cliente sempre lhe deram espaços segmentados para cada cliente na sua plataforma. Cada espaço de trabalho tem os seus próprios modelos, o seu próprio uso de envelopes, a sua própria chave de API. Separação limpa. Mas até agora, a entrega de webhooks era a exceção. Cada evento era encaminhado através de um único webhook ao nível da empresa, o que significava que a sua plataforma era sempre o intermediário das notificações.

Isso é aceitável para algumas arquiteturas. Para outras, é um fator decisivo. Veja-se uma plataforma que permite aos seus clientes ligar os seus próprios CRMs, ERPs ou sistemas de tickets. Cada cliente quer que os eventos de assinatura sejam enviados diretamente para a sua própria pilha. Ou considere um revendedor que oferece aos clientes finais isolamento real em todas as suas integrações. Ou uma equipa de desenvolvimento que quer espaços de trabalho de staging a disparar eventos para um endpoint de teste enquanto a produção dispara para o real.

Em todos esses casos, o webhook tem de viver ao nível do espaço de trabalho ou todo o modelo fica comprometido.

O que está disponível por espaço de trabalho

Cada espaço de trabalho passa agora a ter o conjunto completo de ferramentas de webhook, limitado a si próprio:

• CRUD completo nos endpoints de webhook

• O seu próprio segredo de assinatura, com um período de tolerância de rotação de 7 dias quando o regenera

• Entrega de teste, para poder verificar a configuração sem desencadear eventos reais

• Um registo de eventos por espaço de trabalho

• Um alternador "Ignorar Webhooks da Empresa" se quiser que os webhooks de espaço de trabalho substituam totalmente a entrega ao nível da empresa em vez de funcionarem em paralelo

Esse último alternador é mais importante do que parece. Algumas equipas querem que sejam disparados tanto webhooks da empresa como de espaço de trabalho, porque a sua plataforma ainda precisa de uma visão global dos eventos enquanto os clientes recebem os seus próprios feeds. Outras equipas querem um isolamento limpo, em que os webhooks de espaço de trabalho são a única fonte de verdade. Pode escolher por espaço de trabalho.

Segurança: proteção SSRF em todos os URLs de webhook

Há um ponto que vale a pena assinalar para os programadores que estão a avaliar isto. Toda a validação de URLs de webhook inclui agora proteção contra SSRF, que bloqueia intervalos de IP privados, endpoints de metadados na cloud e tentativas de DNS rebinding. Quando permite que os seus clientes configurem os seus próprios endpoints de webhook dentro de espaços de trabalho que controlam, isto não é opcional. Um cliente pode acidentalmente (ou deliberadamente) apontar um webhook para 169.254.169.254 ou para um IP interno, e sem proteção SSRF estaria a encaminhar pedidos da infraestrutura da Firma para locais a que ninguém deveria aceder.

Isto é tratado ao nível da plataforma, por isso não precisa de criar as suas próprias defesas.

Superfície da API

Algumas adições do lado da API:

• Parâmetro workspace_id em POST /webhooks e GET /webhooks para poder delimitar as operações de webhook a um espaço de trabalho específico

• Novos endpoints para gerir segredos de webhook de espaços de trabalho: POST /workspaces/{id}/webhooks/rotate-secret e GET /workspaces/{id}/webhooks/secret-status

• Cinco novos campos na resposta GET do espaço de trabalho que abrangem o estado da configuração do webhook

Os detalhes completos estão no changelog da API da v1.15.0.

Quando usar webhooks de espaço de trabalho vs webhooks da empresa

Modelo mental rápido:

Os webhooks da empresa são para a sua plataforma. Tudo o que a sua aplicação principal precisa de saber, em relação a todos os clientes, deve passar pela entrega ao nível da empresa. Eventos de faturação, registo de conformidade, análises, fluxos de trabalho internos.

Os webhooks de espaço de trabalho são para os seus clientes. Tudo o que os sistemas de um cliente específico precisem de processar deve passar pela entrega ao nível do espaço de trabalho. Atualizações de CRM, notificações específicas do cliente, integrações de terceiros que tenham configurado por conta própria.

Ambos podem coexistir no mesmo espaço de trabalho, ou pode optar por excluir um espaço de trabalho dos webhooks da empresa por completo. Para a maioria das plataformas multi-inquilino, o padrão certo é webhooks da empresa para eventos críticos da plataforma, mais webhooks de espaço de trabalho que os seus clientes configuram através da sua interface.

Começar

Se já estiver a utilizar os Espaços de Trabalho do Cliente, pode começar a adicionar webhooks de espaço de trabalho hoje mesmo. As integrações de webhook existentes ao nível da empresa continuam a funcionar exatamente como antes. Isto é puramente aditivo.

Comece a usar a Firma.dev gratuitamente, sem necessidade de cartão de crédito. 25 envelopes gratuitos, sem contratos, sem mínimos, e o conjunto completo de ferramentas multi-inquilino, incluindo Espaços de Trabalho do Cliente e Webhooks de Espaço de Trabalho desde o primeiro dia.