Webhooks: transforme qualquer coisa que fale HTTP em anotações

Todo espaço de trabalho já tinha três entradas: o app, a CLI e um assistente de IA via MCP. As três pressupõem que uma pessoa ou um assistente está escrevendo. Muita coisa que vale a pena guardar não é escrita por nenhum dos dois — um deploy que falhou, um comentário no Figma, o pagamento da semana, um formulário que alguém preencheu.

O Notez v0.15.0 adiciona a quarta entrada: uma URL de webhook. Tudo o que consegue enviar uma requisição HTTP agora consegue registrar uma nota.

Uma URL, uma linha de curl

Crie um webhook em Configurações → Integrações → Webhooks, e o Notez entrega uma URL. A configuração é só isso:

curl -X POST "https://api.notez.dev/api/webhooks/notes/<your-token>" \
  -H "Content-Type: application/json" \
  -d '{"title": "Deploy failed on main", "content": "## Details\n- commit abc123", "tags": ["alerts"]}'

A nota aparece com as tags, dentro da nota que você escolheu como destino, na coluna do quadro que você indicou. Tags que você nunca usou são criadas na hora.

Os remetentes que não vão aprender o seu formato

Um formato JSON caprichado funciona quando você controla o remetente. GitHub, Stripe e Sentry não ligam para o formato que você gostaria: eles mandam o próprio payload, e a única coisa que você escolhe é a URL.

Por isso um webhook tem dois modos. Formato do Notez valida com rigor, recusa erros de digitação e oferece título, conteúdo, tags e anexos. Qualquer JSON aceita o que chegar e salva como um bloco de código formatado, com o título tirado do payload se ele tiver um title e do nome do webhook se não tiver. Nada é recusado por ter campos inesperados, e é exatamente essa a ideia.

Anexos, inclusive os que você só tem como link

Uma requisição pode levar até dez arquivos, de três jeitos: como upload de arquivo, em base64 dentro do JSON ou como um link que o Notez baixa para você. O terceiro é o que torna as ferramentas de automação utilizáveis — o Zapier entrega um link para o arquivo, nunca os bytes.

Baixar qualquer coisa para a qual uma URL aponta também é o jeito mais rápido de abrir um buraco na própria infraestrutura. Uma URL de webhook é pública, então "baixe este link" deixaria qualquer pessoa apontar os servidores do Notez para endereços internos e ler o que respondesse. Cada download resolve o endereço primeiro, recusa faixas privadas, internas e de metadados de nuvem, confere de novo depois de cada redirecionamento e se conecta só ao endereço que já conferiu — assim uma segunda resposta de DNS não consegue trocar o destino por algo interno depois da checagem. Arquivos lentos demais, grandes demais ou atrás de login viram links na nota em vez de sumir.

Novas tentativas, e a nota que você não queria duas vezes

Remetentes tentam de novo quando a resposta demora, e uma nova tentativa que cria uma segunda nota é pior do que nenhuma nota. Envie um cabeçalho Idempotency-Key, ou um externalId no corpo, e uma repetição dentro de 24 horas devolve a nota que já existe. O id de entrega do GitHub é lido automaticamente, então as novas tentativas dele são seguras sem configurar nada.

Assinaturas: opcionais de propósito

A URL é a credencial, e URLs vazam — em logs, prints de tela, configurações compartilhadas. Se o remetente consegue assinar as requisições, o Notez confere a assinatura e recusa todo o resto.

Deixei a assinatura opcional, e isso merece uma explicação. A verificação não é uma tranca que eu controlo; é uma checagem de algo que o remetente precisa fazer. O GitHub assina. O Stripe assina. O Zapier, o app Atalhos e a maioria dos scripts não conseguem. Exigir assinatura teria transformado um recurso que funciona com qualquer coisa num recurso que funciona com três serviços, então a URL continua sendo a base e a assinatura é uma segunda camada para os remetentes que conseguem assinar. A lista marca os webhooks sem assinatura, para que esse custo fique visível em vez de esquecido.

Um segredo de assinatura é uma das raras credenciais que o Notez precisa conseguir ler de volta: verificar uma assinatura significa recalculá-la, então o segredo é criptografado, e não guardado como hash. Essa diferença importa mais do que parece, e mudou outra coisa nesta versão.

Já que eu estava nisso: as chaves agora são guardadas como hash

As URLs de webhook são guardadas como hash, porque reconhecer um token nunca exige reproduzi-lo. Já as chaves MCP e da CLI, implementadas antes, eram guardadas em texto puro — legíveis para qualquer um que conseguisse ler o banco de dados.

Agora elas também são guardadas como hash. O efeito prático: uma chave MCP aparece uma única vez, quando você a gera, e depois a tela mostra só os primeiros caracteres. Se você a perder, rotacione a chave. A CLI nunca mostrou a chave dela, de qualquer forma.

Duas coisas menores saíram do mesmo trabalho. Todo webhook cria notas em nome de quem o criou, então remover alguém de um espaço de trabalho agora apaga os webhooks dessa pessoa junto — nenhuma URL sobrevive ao dono. E o log de auditoria, que registra a entrada de cada alteração, agora oculta tudo o que parece uma credencial: ele estava prestes a guardar segredos de assinatura em texto puro bem ao lado das cópias criptografadas.

Para onde apontar

• GitHub — issues, deploys, workflows que falharam, com a verificação de assinatura ligada.

• Zapier ou Make — uma etapa no fim de qualquer automação, que guarda o resultado onde você vai encontrá-lo.

• Cron e CI — relatórios de backup da madrugada, notas de versão, um resumo que de outro jeito ficaria num log que ninguém abre.

• Seu próprio app — pedidos de suporte, cadastros, tudo o que vale a pena guardar ao lado das suas notas.

As notas vindas de um webhook levam o selo WH, então o que você mesmo escreveu nunca se perde no meio delas.

Os detalhes completos, os limites e o passo a passo do GitHub estão no artigo de ajuda sobre webhooks.

Continue lendo

• Primeiros passos com a Notez CLI — os comandos de instalação para macOS, Linux e Windows, onde o notez login guarda a chave e como usar --json em scripts.

• Como montar um sistema de anotações para desenvolvedores — quatro tipos de nota que vale a pena guardar, captura em menos de cinco segundos, nada de pastas e uma revisão semanal de dez minutos.

• Como fazer anotações no terminal — três jeitos de anotar no shell, de echo >> ~/notes.md a uma CLI de captura, e onde cada um falha quando você precisa da nota de volta.