Webhooks de eventos de saída

Esta página explica os webhooks de eventos de saída: o Almirant envia notificações de eventos do projeto para o seu servidor. Para iniciar um agente de um sistema externo, use Webhooks de agentes.

O Almirant envia notificações HTTP de saída ao seu servidor quando ocorrem eventos nos seus projetos. Sempre que um work item é criado, movido entre colunas ou um sprint é fechado, o Almirant envia uma solicitação POST à URL configurada.

Isso é útil para:

• Sincronizar o Almirant com ferramentas externas (Slack, Discord, seu próprio dashboard)
• Disparar pipelines de CI/CD quando uma tarefa muda de estado
• Alimentar sistemas de analytics ou relatórios
• Automatizar fluxos personalizados fora do Almirant

Criar um webhook

1. Acesse Configurações > Webhooks no seu projeto
2. Clique em Criar webhook
3. Preencha os campos:

Campo	Descrição	Exemplo
URL	Endpoint HTTPS que receberá as notificações	https://mi-servidor.com/webhooks/almirant
Eventos	Tipos de eventos que acionam o webhook	work_item.created, sprint.closed
Secret	Chave secreta para validar a autenticidade das solicitações	É gerada automaticamente ou você pode definir a sua

4. Clique em Salvar

Importante

A URL deve estar acessível pela internet e usar HTTPS. O Almirant não enviará webhooks para URLs HTTP sem criptografia, exceto localhost no desenvolvimento.

Eventos disponíveis

Selecione um ou mais eventos ao criar o webhook:

Evento	É acionado quando...
work_item.created	Um novo work item é criado
work_item.updated	Campos de um work item são alterados (título, descrição, prioridade etc.)
work_item.moved	Um work item é movido entre colunas do board
work_item.archived	Um work item é arquivado
lead.created	Um novo lead é criado no CRM
lead.updated	Os dados de um lead são atualizados
lead.stage_changed	Um lead muda de etapa no funnel
sprint.created	Um novo sprint é criado
sprint.closed	Um sprint é fechado

Dica

Se você só precisa reagir a alterações no quadro, selecione apenas os eventos work_item.*. Quanto menos eventos você assinar, menos tráfego o seu servidor receberá.

Verificar a assinatura do webhook

Cada solicitação inclui uma assinatura HMAC-SHA256 no cabeçalho X-Almirant-Signature, que permite verificar que ela realmente vem do Almirant e não foi manipulada.

Como a verificação funciona

1. O Almirant gera um hash HMAC-SHA256 do body da solicitação usando seu secret como chave
2. Inclui o hash no cabeçalho X-Almirant-Signature
3. Seu servidor recalcula o hash com o mesmo secret e os compara

Exemplo em Node.js

import crypto from 'node:crypto';

function verifyWebhookSignature(body, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(body, 'utf8')
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// En tu endpoint:
app.post('/webhooks/almirant', (req, res) => {
  const signature = req.headers['x-almirant-signature'];
  const rawBody = req.rawBody; // Body como string, no parseado

  if (!verifyWebhookSignature(rawBody, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Firma invalida' });
  }

  const event = JSON.parse(rawBody);
  console.log('Evento recibido:', event.type);

  // Procesar el evento...

  res.status(200).json({ received: true });
});

Exemplo em Python

import hmac
import hashlib

def verify_webhook_signature(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode('utf-8'),
        body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Segurança

Sempre verifique a assinatura antes de processar o evento. Nunca confie nos dados do webhook sem validar sua autenticidade. Use timingSafeEqual (ou equivalente) para evitar ataques de timing.

Ver logs de entregas

Cada webhook mantém um histórico de entregas que você pode consultar para depurar problemas.

1. Acesse Configurações > Webhooks
2. Clique no webhook que você quer inspecionar
3. Na aba Entregas, você verá uma lista com:

Coluna	Descrição
Data	Momento exato da entrega
Evento	Tipo de evento que acionou a entrega
Estado	Código HTTP da resposta (200, 500, timeout etc.)
Duração	Tempo de resposta do seu servidor

Clique em qualquer entrega para ver os detalhes completos: cabeçalhos enviados, body do payload e resposta do seu servidor.

Tentativas e falhas

O Almirant tenta novamente entregas com falha automaticamente, com backoff exponencial:

Tentativa	Espera antes da nova tentativa
1	Imediata
2	1 minuto
3	5 minutos
4	30 minutos
5	2 horas

Uma falha ocorre quando:

• Seu servidor responde com um código HTTP >= 400
• Seu servidor não responde em 10 segundos (timeout)
• Não é possível estabelecer conexão com o seu servidor

Após 5 tentativas com falha, a entrega é marcada como falha e não é mais repetida. Você pode reenviá-la manualmente pelo log de entregas.

Nota

Seu servidor deve responder com um código HTTP 2xx, idealmente 200, o mais rápido possível. Se você precisar de processamento demorado, aceite o webhook imediatamente e processe os dados de forma assíncrona.

Desativar ou excluir um webhook

• Desativar: Na lista de webhooks, use o toggle para desativá-lo temporariamente. As entregas são pausadas, mas a configuração é mantida.
• Excluir: Clique no ícone de excluir. Essa ação é irreversível e também apaga o histórico de entregas.