API — Webhooks

Em breve — MVP5

Os webhooks estão planejados para o MVP5. Esta página documenta o comportamento esperado.

Webhooks permitem que sistemas externos recebam notificações em tempo real quando eventos ocorrem no CloudTasks.

Como funcionarão

Você cadastra uma URL de destino (HTTPS) e os eventos que quer receber. Quando o evento ocorre, o CloudTasks faz um POST para a sua URL com o payload do evento em JSON.

Eventos planejados

Issues

Evento	Quando é disparado
issue.created	Nova issue criada
issue.updated	Qualquer campo de issue atualizado
issue.deleted	Issue deletada
issue.status_changed	Status da issue mudou
issue.assigned	Responsável atribuído ou alterado

Projetos

Evento	Quando é disparado
project.created	Novo projeto criado
project.updated	Configurações do projeto atualizadas
project.archived	Projeto arquivado

Membros

Evento	Quando é disparado
member.invited	Convite enviado
member.joined	Convite aceito
member.removed	Membro removido da organização

Formato do payload (planejado)

{
  "event": "issue.status_changed",
  "timestamp": "2026-04-18T12:00:00Z",
  "organization": {
    "id": "01J8X...",
    "slug": "acme-corp"
  },
  "workspace": {
    "id": "01J8X...",
    "slug": "produto"
  },
  "data": {
    "issue": {
      "id": "01J8X...",
      "key": "FE-7",
      "title": "Corrigir bug no login"
    },
    "old_status": { "name": "A fazer", "category": "todo" },
    "new_status": { "name": "Em progresso", "category": "in_progress" },
    "changed_by": { "id": "01J8X...", "name": "Gabriel Mowses" }
  }
}

Segurança (planejado)

Cada webhook terá um secret gerado no cadastro. O CloudTasks enviará uma assinatura HMAC-SHA256 no header X-CloudTasks-Signature para verificar a autenticidade do payload.

X-CloudTasks-Signature: sha256=abc123...

Verifique a assinatura no seu endpoint antes de processar o payload.

Retentativas (planejado)

Se o endpoint retornar um status >= 400 ou não responder em 10 segundos, o CloudTasks tentará novamente com backoff exponencial: 1min, 5min, 30min, 2h, 24h.

Após 5 falhas consecutivas, o webhook é desativado automaticamente e um e-mail de aviso é enviado.