Notificações por Webhook

Webhooks permitem que você receba notificações HTTP POST em tempo real sempre que algo mudar no seu workspace do Archyl. Crie um webhook, aponte para a sua URL, escolha os eventos que importam para você, e o Archyl notificará o seu endpoint toda vez que esses eventos forem disparados.

Visão Geral

Quando um evento ocorre — um sistema é criado, um release é implantado, uma ADR é atualizada — o Archyl envia uma requisição HTTP POST para todos os webhooks inscritos naquele evento. Seu endpoint recebe um payload JSON descrevendo o que aconteceu, quem fez e a qual projeto pertence.

Casos de uso comuns:

• Notificações no Slack ou Teams quando mudanças na arquitetura são feitas
• Gatilhos de CI/CD quando um novo release é criado
• Log de auditoria em um sistema externo
• Dashboards personalizados que reagem a eventos de arquitetura
• Pipelines de automação que executam quando descobertas são concluídas

Eventos Suportados

Elementos de Arquitetura

Gerenciamento de Projetos

Documentação

Colaboração e Análise

Criando um Webhook

1. Vá em Configurações da Organização e selecione a aba Webhooks
2. Clique em Novo Webhook
3. Preencha a configuração:

4. Clique em Criar

O webhook começa a receber eventos imediatamente.

Formato do Payload

Cada entrega de webhook envia um payload JSON com esta estrutura:

{
  "event": "system.created",
  "timestamp": "2026-03-10T14:30:00Z",
  "data": {
    "entityType": "system",
    "entityName": "Payment Service",
    "action": "created",
    "userName": "vincent",
    "projectId": "a1b2c3d4-...",
    "projectName": "My Project"
  }
}

O header Content-Type é sempre application/json.

Segurança

Headers da Requisição

Cada entrega de webhook inclui estes headers:

Verificação de Assinatura HMAC-SHA256

Se você definir um token secreto ao criar o webhook, o Archyl assina cada payload usando HMAC-SHA256. A assinatura é enviada no header X-Archyl-Signature com o formato:

sha256=<digest HMAC-SHA256 codificado em hex>

Para verificar uma entrega:

1. Leia o corpo bruto da requisição (os bytes exatos, antes de qualquer parsing JSON)
2. Leia o header X-Archyl-Signature e remova o prefixo sha256= para obter a assinatura em hex
3. Compute um hash HMAC-SHA256 do corpo bruto usando seu token secreto como chave
4. Codifique o resultado em hex e compare com a assinatura do passo 2 usando uma comparação em tempo constante
5. Rejeite a requisição se não forem iguais

Exemplo em Go:

func verifyArchylWebhook(r *http.Request, secret string) ([]byte, error) {
    body, err := io.ReadAll(r.Body)
    if err != nil {
        return nil, err
    }

    header := r.Header.Get("X-Archyl-Signature")
    if !strings.HasPrefix(header, "sha256=") {
        return nil, fmt.Errorf("missing or invalid signature header")
    }
    signature := strings.TrimPrefix(header, "sha256=")

    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write(body)
    expected := hex.EncodeToString(mac.Sum(nil))

    if !hmac.Equal([]byte(expected), []byte(signature)) {
        return nil, fmt.Errorf("signature mismatch")
    }
    return body, nil
}

Exemplo em Node.js:

const crypto = require("crypto");

function verifyArchylWebhook(req, secret) {
  const header = req.headers["x-archyl-signature"] || "";
  if (!header.startsWith("sha256=")) {
    throw new Error("Missing or invalid signature header");
  }
  const signature = header.slice("sha256=".length);

  const body = req.rawBody; // use raw body, not parsed JSON
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");

  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
    throw new Error("Signature mismatch");
  }
  return JSON.parse(body);
}

Exemplo em Python:

import hmac
import hashlib

def verify_archyl_webhook(body: bytes, header: str, secret: str) -> dict:
    if not header.startswith("sha256="):
        raise ValueError("Missing or invalid signature header")
    signature = header.removeprefix("sha256=")

    expected = hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, signature):
        raise ValueError("Signature mismatch")
    return json.loads(body)

Sempre use comparação em tempo constante (hmac.Equal, crypto.timingSafeEqual, hmac.compare_digest) para prevenir ataques de timing. Sempre verifique contra o corpo bruto da requisição -- fazer parsing e re-serializar o JSON pode alterar a representação em bytes e quebrar a assinatura.

Histórico de Entregas

Cada webhook mantém um log das entregas recentes. Para visualizar:

1. Vá em Configurações da Organização > Webhooks
2. Clique no nome do webhook
3. Abra a aba Entregas

Cada registro de entrega mostra:

As entregas são retidas por 7 dias. Após esse período, são automaticamente removidas.

Um badge verde indica uma entrega bem-sucedida (resposta 2xx). Vermelho indica uma falha (não-2xx ou timeout).

Testes

Antes de confiar em um webhook em produção, verifique se ele funciona:

1. Abra a página de detalhes do webhook
2. Clique em Enviar Teste
3. O Archyl envia um payload de teste para o seu endpoint com event: "webhook.test"
4. Verifique a aba Entregas para confirmar o recebimento e inspecionar a resposta

A entrega de teste usa o mesmo mecanismo de assinatura dos eventos reais, então você pode validar sua lógica de verificação de assinatura ao mesmo tempo.

Política de Retentativa

Quando uma entrega falha (resposta não-2xx ou timeout de rede), o Archyl tenta novamente automaticamente:

Após 3 retentativas falhadas, a entrega é marcada como falha. Você pode re-disparar manualmente qualquer entrega falhada na aba Entregas clicando em Tentar Novamente.

Se um webhook falhar consistentemente por 24 horas, o Archyl o desabilita e envia uma notificação para os administradores da organização. Reative-o nas configurações do webhook assim que o problema for resolvido.

Filtragem por Projetos

Por padrão, um webhook recebe eventos de todos os projetos da organização. Para restringir o escopo:

1. Edite o webhook
2. Em Projetos, selecione um ou mais projetos
3. Salve

Apenas eventos originados dos projetos selecionados dispararão entregas. Isso é útil quando diferentes equipes gerenciam diferentes projetos e precisam apenas de notificações sobre o próprio trabalho.

Você pode atualizar o filtro de projetos a qualquer momento sem precisar recriar o webhook.

Boas Práticas

Responda Rapidamente

Seu endpoint deve retornar uma resposta 2xx em até 10 segundos. Se você precisar fazer processamento pesado, aceite o webhook imediatamente e processe o trabalho de forma assíncrona em um job em segundo plano.

Verifique as Assinaturas

Sempre defina um token secreto e verifique o header X-Archyl-Signature. Isso garante que os payloads realmente vêm do Archyl e não foram adulterados.

Use HTTPS

Sempre use um endpoint HTTPS. O Archyl não entregará webhooks para URLs HTTP simples.

Filtre por Projeto

Se sua organização tem muitos projetos, restrinja os webhooks aos projetos que importam para você. Isso reduz o ruído e evita processamento desnecessário do seu lado.

Trate Duplicatas

Em casos raros (retentativas de rede, failover de infraestrutura), seu endpoint pode receber o mesmo evento mais de uma vez. Use os campos timestamp e event para detectar e deduplicar.

Monitore a Saúde das Entregas

Verifique a aba Entregas periodicamente. Um padrão de falhas pode indicar problemas no endpoint, regras de firewall ou credenciais expiradas do seu lado.

Próximos Passos

• Integrações do Marketplace — Conecte serviços externos e exiba dados em tempo real nos seus dashboards
• Gerenciamento de Releases — Acompanhe implantações em toda a sua arquitetura
• Insights de Arquitetura — Detecte problemas arquiteturais automaticamente