Webhooks: Notificações em Tempo Real para Mudanças na Arquitetura

Na semana passada, um time me contou que renomeou um sistema central no Archyl — mudou "UserService" para "AccountService" em todo o modelo C4, atualizou os relacionamentos, reescreveu a ADR. Um trabalho limpo e completo. O problema? O time de plataforma que dependia daquele sistema só ficou sabendo quatro dias depois, quando o pipeline de deploy referenciou um nome que não existia mais.

Ninguém avisou. Não porque alguém foi descuidado — simplesmente não existia um mecanismo para isso. A documentação de arquitetura normalmente funciona no modelo pull. Você vai lá e olha o diagrama. Você vai lá e lê a ADR. Se você não for olhar, você não sabe.

Esse é o mesmo padrão que assolava o desenvolvimento de software antes das notificações de CI/CD se tornarem padrão. Mudanças de código eram algo que você descobria quando fazia pull da main. Hoje, cada merge, cada build que falha, cada deploy dispara uma notificação em algum lugar. Mudanças na arquitetura merecem o mesmo tratamento.

Notificações Push para Sua Arquitetura

O Archyl agora suporta webhooks. Quando algo muda no seu modelo C4 — um sistema é criado, um container é excluído, um relacionamento é atualizado, uma release é publicada — o Archyl envia um HTTP POST para qualquer endpoint que você configurar, com um payload JSON descrevendo exatamente o que aconteceu.

A ideia é simples: sua arquitetura é um sistema vivo. Pessoas e ferramentas devem poder se inscrever nas mudanças da mesma forma que se inscrevem em eventos de deploy ou notificações de pull requests. Em vez de perguntar "mudou alguma coisa?", a resposta vem até você.

44 Tipos de Eventos

Não queríamos lançar um sistema de notificações que cobrisse apenas metade do modelo. Os webhooks disparam em tudo que o Archyl rastreia:

Elementos C4 — Criação, atualização e exclusão de sistemas, containers, componentes e elementos de código. O núcleo do seu modelo de arquitetura.

Relacionamentos — Quando conexões entre elementos são criadas, modificadas ou removidas. Esse é frequentemente o sinal mais importante — uma nova dependência entre dois sistemas é o tipo de mudança que múltiplos times precisam saber.

ADRs e Documentação — Architecture Decision Records e documentações de projeto sendo criadas, atualizadas ou excluídas. Quando alguém escreve uma nova ADR explicando por que o time está migrando de REST para gRPC, as pessoas afetadas devem ficar sabendo imediatamente, não três sprints depois.

Fluxos — Mudanças em fluxos de usuário e de sistema. Novos fluxos, etapas atualizadas, fluxos excluídos.

Overlays — Mudanças de agrupamento visual nos seus diagramas.

Releases — Eventos de deploy em diferentes ambientes. Combinado com o gerenciamento de releases, isso oferece um pipeline completo de notificações de deploy baseado em push.

Requests — Solicitações de mudança de arquitetura sendo abertas, revisadas ou mergeadas.

Contratos de API e Canais de Eventos — Mudanças em especificações e atualizações de mensageria assíncrona vinculadas à sua arquitetura.

Discovery e Insights — Conclusões de discovery alimentado por IA e novos insights de arquitetura.

Quarenta e quatro tipos de eventos no total. Você escolhe os que importam para você — inscreva-se em todos ou apenas nos cinco eventos que fazem sentido para o seu fluxo de trabalho.

Como Funciona

Configurar um webhook leva cerca de trinta segundos.

Você dá um nome (algo descritivo — "Notificações do Slack", "Sync de log de auditoria", "Trigger de CI"). Você fornece uma URL — qualquer endpoint HTTP que possa receber uma requisição POST. Opcionalmente, você define um secret para verificação de assinatura. Depois, escolhe quais eventos devem acioná-lo.

Você também pode limitar o escopo de um webhook a projetos específicos. Um webhook que abrange toda a organização e dispara a cada mudança em todos os projetos é útil para logs de auditoria. Um webhook com escopo de projeto que dispara apenas em eventos de release do seu sistema de pagamentos é útil para o time que o mantém.

Quando um evento correspondente ocorre, o Archyl envia um HTTP POST para a sua URL com um payload JSON contendo:

• Tipo de evento — Qual dos 44 eventos acionou essa entrega
• Entidade — Os detalhes completos do elemento que mudou
• Ator — Quem fez a mudança (ID do usuário, nome, email)
• Projeto — Em qual projeto isso aconteceu
• Timestamp — Quando a mudança ocorreu
• Organização — A qual organização isso pertence

O payload fornece tudo o que você precisa para reagir à mudança — exibi-la, registrá-la, acionar um pipeline ou sincronizá-la com outro sistema.

Segurança: Assinaturas HMAC-SHA256

Cada requisição de webhook inclui um header X-Archyl-Signature com o formato sha256=<hex digest> — um hash HMAC-SHA256 do corpo bruto da requisição, calculado usando o seu secret. Você também receberá X-Archyl-Event (o tipo de evento) e User-Agent: Archyl-Webhook/1.0 para que possa identificar a origem.

No lado receptor, você remove o prefixo sha256=, recalcula o hash HMAC-SHA256 com a sua cópia do secret sobre os bytes brutos do corpo, e compara usando comparação em tempo constante. Se forem iguais, a requisição é autêntica. Se não forem, alguém está enviando eventos forjados para você.

Esse é o mesmo esquema de assinatura usado pelo GitHub, Stripe e pela maioria dos provedores de webhooks. É simples, bem compreendido e fácil de implementar em qualquer linguagem. Sem fluxos OAuth, sem rotação de tokens, sem gerenciamento de certificados. Apenas um secret compartilhado e um hash. Consulte a documentação de webhooks para exemplos completos de verificação em Go, Node.js e Python.

Se você não definir um secret, o header de assinatura é omitido. Tudo bem para endpoints internos atrás de uma VPN. Não recomendado para nada exposto à internet.

O Que Você Pode Construir Com Isso

O caso de uso mais óbvio são notificações em chat. Slack, Microsoft Teams e Discord suportam webhooks de entrada — cole a URL deles no Archyl, selecione os eventos que te interessam, e as mudanças de arquitetura começam a aparecer no seu canal. Um novo sistema foi adicionado. Uma ADR foi aprovada. Uma release foi publicada em produção. Seu time vê tudo sem abrir o Archyl.

Mas notificações são apenas o começo.

Sincronização com sistemas externos — Envie mudanças de arquitetura para um CMDB, uma wiki interna ou um catálogo de serviços. Quando um container é renomeado no Archyl, seu catálogo de serviços atualiza automaticamente.

Acionar pipelines de CI/CD — Quando uma solicitação de mudança de arquitetura é mergeada, dispare um pipeline que regenera configuração de infraestrutura, atualiza módulos Terraform ou valida que o deploy real corresponde à arquitetura documentada.

Trilha de auditoria — Encaminhe cada evento para um sistema de logging externo — Elasticsearch, Splunk, um banco de dados simples append-only. Sete dias de histórico de entregas no Archyl são úteis para debugging; um log externo permanente é útil para compliance.

Dashboards personalizados — Construa um dashboard interno que reage a eventos de arquitetura em tempo real. Acompanhe com que frequência a arquitetura muda, quais times são mais ativos, quais sistemas são mais voláteis.

O ponto é que os webhooks transformam o Archyl em uma fonte de eventos. Seu modelo de arquitetura se torna algo em que outros sistemas podem se inscrever, reagir e construir por cima.

Rastreamento de Entregas

Cada entrega de webhook é registrada. Você pode ver o histórico completo de qualquer webhook: qual evento o acionou, o payload da requisição que foi enviado, o código de status da resposta, o corpo da resposta e os timestamps de quando foi enviado e quando a resposta chegou.

As entregas são retidas por sete dias. Tempo suficiente para debugar problemas de integração, curto o bastante para que não fiquemos armazenando os corpos de resposta do seu endpoint indefinidamente.

Quando uma entrega falha — um 500 do seu servidor, um timeout, um erro de resolução DNS — ela aparece com status vermelho. Você pode inspecionar o erro, corrigir seu endpoint e reenviar com um clique. O reenvio manda exatamente o mesmo payload, para que seu endpoint processe o evento original como se tivesse funcionado da primeira vez.

Sem retentativas automáticas. Consideramos backoff exponencial, mas na prática, a maioria das falhas de webhook é transiente (seu servidor estava reiniciando) ou estrutural (a URL está errada). Para falhas transientes, o botão de reenvio manual é mais rápido do que esperar o backoff. Para falhas estruturais, retentativas automáticas só geram ruído.

Primeiros Passos

1. Vá em Configurações da Organização > Webhooks
2. Clique em Criar Webhook
3. Insira um nome, cole a URL do seu endpoint, defina um secret
4. Selecione os eventos que você quer assinar
5. Opcionalmente, filtre por projetos específicos
6. Clique em Enviar Teste para verificar se seu endpoint recebe o payload
7. Salve, e está no ar

A entrega de teste envia um evento ping com um payload de exemplo para que você confirme que seu endpoint está acessível, que seu secret está configurado corretamente e que seu handler processa o JSON como esperado. Faça isso antes de se inscrever em eventos reais.

Arquitetura como um Fluxo de Eventos

Estamos construindo uma versão da documentação de arquitetura que não é um artefato estático — é uma parte viva e conectada do seu fluxo de desenvolvimento. As Integrações do Marketplace trazem dados externos para dentro da sua arquitetura. Os Webhooks enviam dados de arquitetura para fora, para as suas ferramentas.

A combinação é poderosa. Seu workspace de arquitetura não é apenas um lugar onde você vai olhar diagramas. É um hub que recebe dados operacionais das suas ferramentas de monitoramento e emite eventos de mudança para suas ferramentas de comunicação e automação. Os dados fluem nas duas direções.

Documentação de arquitetura que ninguém olha é inútil. Documentação de arquitetura que te notifica quando importa — isso é infraestrutura.

Quer ver como outras funcionalidades conectam sua arquitetura ao seu fluxo de trabalho? Confira as Integrações do Marketplace para trazer dados ao vivo para seus diagramas, ou o Gerenciamento de Releases para acompanhar deploys em todo o seu modelo C4.