Skip to content
ver .md original

Reaja a mudanças no Plan com webhooks

Receba eventos do Dailybot Plan no seu próprio endpoint: os 25 eventos tasks.*, o envelope do payload sem títulos de tarefas, a verificação do X-BEARER e a busca de detalhes com a sua própria credencial.

Beta

Plan está em beta. Tudo o que está em /plan no aplicativo web, os comandos da CLI e da agent skill para projetos, metas, quadros e tarefas, e a API pública /v1/plan/ podem mudar antes da disponibilidade geral. Quer testar com sua equipe? Escreva para [email protected].

Consultas periódicas funcionam bem para uma tela que alguém está olhando. Para um servidor que precisa reagir a cada mudança (sincronizar com outra ferramenta, avisar um canal, atualizar um relatório), assine os eventos do Plan e deixe que o Dailybot chame você.

1. Assine pelos webhooks da sua organização

Os eventos do Plan são entregues pelos mesmos webhooks de saída que todos os outros eventos do Dailybot. Não existe um endpoint de webhook separado em /v1/plan/. Crie a assinatura no aplicativo web ou com a API de Webhooks, escolha os eventos tasks.* de que você precisa e defina um segredo para o header X-BEARER. Veja Webhooks e eventos para a configuração.

2. Os 25 eventos do Plan

Objeto Eventos
Tarefa tasks.task.created · tasks.task.updated · tasks.task.state_changed · tasks.task.owner_changed · tasks.task.moved · tasks.task.comment_created · tasks.task.archived · tasks.task.participant_added · tasks.task.participant_removed
Quadro tasks.board.created · tasks.board.updated · tasks.board.archived · tasks.board.restored · tasks.board.member_added · tasks.board.member_removed
Projeto tasks.project.created · tasks.project.updated · tasks.project.member_added · tasks.project.member_removed · tasks.project.archived · tasks.project.restored
Meta tasks.goal.created · tasks.goal.updated · tasks.goal.archived · tasks.goal.restored
  • Não existe tasks.task.deleted: arquivar é a exclusão, então escute tasks.task.archived.
  • Novos eventos são adicionados com o tempo. Ignore os eventos que você não reconhece em vez de falhar.
  • Algumas mudanças aparecem apenas no feed de atividade, não como webhooks (por exemplo, um marco removido, registrado como project.milestone_deleted).

3. O que chega: identificadores, nunca títulos

Toda entrega é um POST em JSON com o envelope padrão. No Plan, body é o registro do evento:

{
  "event": "tasks.task.state_changed",
  "event_timestamp": "2026-09-25T10:14:02Z",
  "hook": { "id": "wh-1234-abcd", "name": "Tasks sync" },
  "body": {
    "event": "tasks.task.state_changed",
    "occurred_at": "2026-09-25T10:14:02.113954Z",
    "observed_at": "2026-09-25T10:14:02.113954Z",
    "organization_uuid": "00000000-0000-4000-8000-000000000101",
    "actor": { "kind": "user", "uuid": "00000000-0000-4000-8000-00000000000c" },
    "correlation_id": "00000000-0000-4000-8000-000000000102",
    "entity": { "type": "task", "uuid": "00000000-0000-4000-8000-000000000005", "key": "ENG-142" },
    "data": {
      "from_state_uuid": "00000000-0000-4000-8000-000000000003",
      "to_state_uuid": "00000000-0000-4000-8000-000000000004"
    }
  }
}

Nenhum título, descrição, texto de comentário ou nome de etiqueta aparece em um payload. Isso é intencional: uma URL de webhook é o destino menos confiável para onde um evento pode ir. A key da tarefa é o único campo legível por pessoas. Quando você precisar do conteúdo, busque-o com uma credencial sua, que é recusada se não tiver permissão para vê-lo:

curl -sS "https://api.dailybot.com/v1/plan/tasks/ENG-142/" \
  -H "X-API-KEY: $DAILYBOT_API_KEY" | jq '{key, title, state: .state.name}'

4. Verifique cada entrega

As entregas não são assinadas. Em vez disso, cada requisição traz um header X-BEARER com o segredo que você definiu na assinatura. Rejeite qualquer outra coisa, compare em tempo constante e aceite apenas HTTPS:

import { timingSafeEqual } from 'node:crypto';

function isFromDailybot(req) {
  const received = Buffer.from(req.headers['x-bearer'] ?? '');
  const expected = Buffer.from(process.env.DAILYBOT_WEBHOOK_SECRET);
  return received.length === expected.length && timingSafeEqual(received, expected);
}

OAuth 2.0 também está disponível para autenticar webhooks; veja Webhooks e eventos.

5. Trate a entrega do jeito certo

  • Responda rápido com um 2xx e faça o trabalho de forma assíncrona.
  • Torne o processamento idempotente: use como chave o registro do evento (entity.uuid, event, occurred_at) para que uma entrega repetida ou uma nova tentativa sua não cause problemas.
  • Ordene por occurred_at, não pela hora de chegada.
  • Leia de novo antes de agir quando a decisão depender do estado atual; o evento diz o que mudou, a API diz o que vale agora.

Referência