Registro de webhooks para entrega push

Agentes de código já empurram progresso para o Dailybot pela superfície de reporting do agente. Webhooks estendem esse modelo na direção oposta: o Dailybot avisa os sistemas de vocês quando algo relevante acontece, para integrações reagirem quase em tempo real sem polling.

Entrega push versus polling

Polling significa que o serviço pergunta repetidamente “tem algo novo?” em um intervalo. É fácil de raciocinar, mas adiciona latência (só descobrem depois do próximo poll), gasta cota em respostas vazias e ainda arrisca perder sequências rápidas se o intervalo for longo.

Entrega push inverte o fluxo: o Dailybot chama uma URL que vocês controlam quando um evento dispara. O código roda porque algo mudou, não porque um cron tocou. Para fluxos de agentes—relatórios recebidos, inbox atualizado, limites de saúde cruzados—push costuma ser o padrão melhor quando há um endpoint HTTPS acessível.

Registrar um endpoint de webhook

O registro costuma ser feito em configurações do workspace onde o Dailybot expõe integrações de saída. Vocês informam:

• Uma URL HTTPS que a equipe controla (sem certificados autoassinados em produção).
• Metadados opcionais como rótulo, tag de ambiente ou a quais famílias de eventos assinar, conforme a interface do produto.

Depois de salvar, o Dailybot associa essa URL ao workspace e passa a tentar entrega para os tipos de evento assinados. Tratem o registro como configuração documentada quando possível: registrem a URL, o serviço responsável e o procedimento de rotação de segredos onde já guardam chaves de API.

Forma do payload e o que importa para agentes

Nomes de campo evoluem com o produto, mas corpos de webhook costumam ser JSON e incluem:

• Um tipo de evento ou categoria para ramificar lógica sem inferir a partir de payloads parciais.
• Um timestamp ou identificador de evento para ordenação e deduplicação.
• Contexto ligando o evento a workspace, projeto ou identidade do agente—alinhado ao que já enviam em relatórios e metadata.

Pensem no webhook como um espelho estruturado da atividade que os agentes já geraram: relatório enviado, digest pronto ou gancho de automação downstream. O parse deve ser defensivo: campos desconhecidos podem aparecer quando o Dailybot ganha capacidades; ignorem o que não precisam.

Autenticação e verificação das chamadas

Como a URL está na internet pública, qualquer cliente HTTP poderia fazer POST. A verificação fecha essa brecha.

Integrações no estilo Dailybot costumam trazer um segredo compartilhado ou assinatura HMAC sobre o corpo bruto da requisição. O handler deve:

1. Ler o corpo bruto antes do parse JSON para verificar a assinatura.
2. Calcular a assinatura esperada com o algoritmo e segredo documentados.
3. Comparar com comparação em tempo constante para resistir a ataques de timing.
4. Opcionalmente impor uma janela de diferença de timestamp se as assinaturas incluírem claims temporais.

Nunca registrem segredos completos nem material de assinatura sem redação. Rotacionem segredos quando alguém sair do time ou se houver suspeita de exposição.

Novas tentativas, erros e desenho do handler

Emissores de webhook quase sempre tentam de novo em caso de falha: quedas de rede, deploys e sobrecarga são normais. Esperem entrega pelo menos uma vez: o mesmo evento lógico pode chegar mais de uma vez.

Retornem 2xx assim que validarem e persistirem o suficiente para terminar o processamento depois. Transações longas no banco ou chamadas a terceiros devem rodar de forma assíncrona depois de reconhecer o HTTP—caso contrário o Dailybot pode estourar timeout e tentar de novo enquanto o trabalho ainda roda.

Se retornarem 4xx por payloads malformados, o emissor pode não tentar de novo (bug de vocês). Se retornarem 5xx ou timeout, esperem novas tentativas com backoff. Implementem chaves de idempotência a partir de IDs de evento para que entregas duplicadas não criem tickets, cobranças ou deploys duplicados.

Boas práticas de segurança e operação

• Usem apenas HTTPS e mantenham TLS atualizado no ingress.
• Autentiquem cada requisição de forma criptográfica; não confiem só na URL ser obscura.
• Escopiem o segredo do webhook por ambiente (staging versus produção).
• Apliquem rate limiting e monitorem o endpoint contra abuso alheio ao Dailybot.
• Alertem sobre taxas de erro altas para que deriva silenciosa não quebre automação orientada por agentes.

Como isso se encaixa no sistema amplo de reporting de agentes

Reporting de agente é a fonte da verdade sobre o que agentes de código fizeram: mensagens estilo standup, JSON estruturado para milestones, sinais de saúde e pulls do inbox. Webhooks são a camada de fan-out: permitem que CI, painéis internos ou orquestradores reajam no instante em que há informação nova—sem substituir chamadas API autenticadas para ações que precisam partir do agente ou serviço de vocês.

Juntos, o modelo é: agentes empurram para o Dailybot; o Dailybot armazena e exibe visibilidade para pessoas; webhooks opcionalmente avisam outros sistemas assim que existe informação nova—sem substituir o API autenticado.

---

Para esquemas em nível de campo e a lista de eventos mais recente, sigam a documentação oficial para desenvolvedores do Dailybot junto com as configurações do workspace.