Automações por webhook

Basic ou superior

As Automações exigem o Basic ou superior. Basic: 1 automação, Pro: 3, Ultra: 10. No Free, a linha mostra Faça upgrade para desbloquear as Automações.

Um webhook é um endereço web que recebe dados automaticamente. Com as Automações, o TellDone envia cada nota nova, com as tarefas e os eventos dela, para esse endereço assim que a nota fica pronta, e cada relatório novo quando o relatório fica pronto, para que ferramentas como o Zapier, o Make ou o n8n possam agir sobre eles. Cada tarefa e cada evento é enviado como um envio separado.

Escolher o que enviar

Cada automação tem as próprias configurações em O que enviar. Escolha um ou qualquer combinação:

• Nota - a nota processada completa (título, transcrição, resumo, tipo, tags, prioridade, idioma e data de criação)
• Nota + áudio - no plano Ultra, adiciona a cada envio de nota um link de download do arquivo de áudio, válido por 24 horas. Mantenha Nota ativada: sem ela, nenhuma nota é enviada
• Tarefas - um envio por tarefa extraída
• Eventos - um envio por evento de calendário extraído
• Relatórios - um envio por relatório diário, semanal, mensal ou anual gerado (os tipos de relatório que o seu plano inclui). Os marcadores de dias tranquilos e os relatórios curtos de semanas tranquilas não são enviados

Você pode mudar isso a qualquer momento nas configurações da automação - as mudanças valem só para os novos envios.

Escolher quando enviar

Abaixo das opções de dados, quatro botões separados decidem quais mudanças disparam um envio: Criado, Atualizado, Concluídas e Excluído. Um gatilho só funciona junto com o botão de dados correspondente acima dele. Por exemplo, Concluídas envia as tarefas concluídas só se Tarefas estiver ativado.

Criado é enviado para as notas que o TellDone faz a partir de uma gravação ou de uma nota de texto, e para as tarefas e os eventos encontrados nelas. As tarefas e os eventos que você adiciona à mão ou com um assistente de IA, e os itens novos do Adicionar por voz, não são enviados como Criado. Atualizado, Concluídas e Excluído são enviados quando você altera um item no app ou com o Adicionar por voz. As mudanças feitas pelo Smart Context, por um assistente de IA ou no Todoist, no Notion ou no Microsoft To Do não geram um envio.

O campo event de cada envio diz o que aconteceu, por exemplo task.created, task.completed ou calendar_event.updated.

Configurar um webhook

1. Vá em Configurações > Integrações > Automações
2. Toque em Nova automação

3. Digite um nome (por exemplo, "Meu webhook do Zapier")
4. Cole a URL do webhook do seu serviço de automação
5. Escolha quais dados enviar (Nota, Nota + áudio no Ultra, Tarefas, Eventos, Relatórios) e quais gatilhos usar (Criado, Atualizado, Concluídas, Excluído)
6. Se quiser, adicione um cabeçalho de autenticação - um token enviado como o cabeçalho Authorization para endpoints protegidos
7. Toque em Salvar
8. Copie a chave secreta - ela aparece completa só quando você cria a automação ou depois de renová-la. Você precisa dela para conferir que os envios vêm mesmo do TellDone (veja Verificar assinaturas de webhook)
9. Toque em Testar envio para mandar um exemplo de payload ao seu endpoint sem alterar nenhum dos seus dados. Você verá Sucesso com o código HTTP e o tempo de resposta, ou Erro com o motivo. Os envios de teste não aparecem no log de envios

O que é enviado

Todo envio é um objeto JSON com três campos: event (o tipo de evento), timestamp e data (o conteúdo em si). Os envios de teste também incluem "test": true. Veja como é cada tipo de evento.

Notas (note.created)

Contém o título gerado pela IA, a transcrição completa, o resumo, o tipo da nota, as tags, a prioridade, o idioma e a data de criação.

{
  "event": "note.created",
  "timestamp": "2026-02-27T14:38:00.512345+00:00",
  "data": {
    "note_id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Meeting notes - Project Alpha",
    "transcript": "Full transcript text...",
    "summary": "Brief AI-generated summary...",
    "type": "meeting",
    "tags": ["work", "project-alpha"],
    "priority": "high",
    "language": "en",
    "created_at": "2026-02-27T10:00:00.284117+00:00"
  }
}

No plano Ultra, os envios de nota também podem incluir um link para a gravação de áudio (audio_url, audio_format, duration_seconds). O link expira após 24 horas. Ative isso com a opção Nota + áudio na automação.

Tarefas (task.created)

Um envio por tarefa. Uma nota com 3 tarefas envia 3 envios separados.

{
  "event": "task.created",
  "timestamp": "2026-02-27T14:38:01.204718+00:00",
  "data": {
    "note_id": "550e8400-...",
    "note_title": "Meeting notes - Project Alpha",
    "task_id": "660f9511-...",
    "title": "Send proposal to client",
    "description": "Include pricing for Q2",
    "priority": "high",
    "due_date": "2026-03-01",
    "reminder_at": "2026-02-28T09:00:00+00:00",
    "tags": ["work"],
    "status": "todo",
    "cancel_reason": null,
    "cancelled_at": null,
    "created_at": "2026-02-27T10:00:00.284117+00:00"
  }
}

Eventos (calendar_event.created)

Um envio por evento de calendário.

{
  "event": "calendar_event.created",
  "timestamp": "2026-02-27T14:38:02.093361+00:00",
  "data": {
    "note_id": "550e8400-...",
    "note_title": "Meeting notes",
    "event_id": "770a0622-...",
    "title": "Team standup",
    "description": "Weekly sync",
    "start": "2026-03-03T07:00:00+00:00",
    "end": "2026-03-03T07:30:00+00:00",
    "location": "Zoom",
    "is_all_day": false,
    "attendees": ["alice@example.com"],
    "tags": ["work"],
    "created_at": "2026-02-27T10:00:00.284117+00:00",
    "timezone": "Europe/Istanbul",
    "start_local": "2026-03-03T10:00:00+03:00",
    "end_local": "2026-03-03T10:30:00+03:00",
    "start_date": "2026-03-03",
    "end_date": "2026-03-03"
  }
}

start e end estão em UTC. start_local, end_local, start_date e end_date usam o seu fuso horário (timezone). Em um evento de dia inteiro, end_date é o último dia do evento.

Relatórios (report.created)

Enviado quando um relatório diário, semanal, mensal ou anual é gerado.

{
  "event": "report.created",
  "timestamp": "2026-02-28T00:05:00.731902+00:00",
  "data": {
    "report_id": "880b1733-...",
    "report_type": "daily",
    "period_start": "2026-02-27",
    "period_end": "2026-02-27",
    "content_md": "# Daily Report\n\n...",
    "content_json": {
      "productivity_score": 72,
      "day_type": "planning",
      "tasks_created": 5,
      "tasks_completed": 3
    },
    "created_at": "2026-02-28T00:05:00.418253+00:00"
  }
}

Segurança

Todo envio é assinado com HMAC-SHA256 usando a chave secreta da sua automação. Os seguintes cabeçalhos vão em cada envio:

• X-LP-Signature - a assinatura HMAC-SHA256 (sha256=...)
• X-LP-Timestamp - timestamp Unix usado na assinatura
• X-LP-Event - o tipo de evento (por exemplo note.created, task.completed, calendar_event.updated, report.created)
• X-LP-Delivery-Id - ID único do envio (útil para eliminar duplicatas)
• User-Agent - sempre TellDone-Webhooks/1.0

O TellDone só envia um cabeçalho Authorization se você adicionar um cabeçalho de autenticação na automação. Você pode usar dois formatos: Header-Name: value envia um cabeçalho com nome e um valor simples envia Authorization: <value>. Sua chave secreta nunca é enviada em um cabeçalho.

Cada automação tem a própria chave secreta, então renovar uma não afeta nenhum dos seus outros webhooks. A chave aparece completa só quando você cria a automação ou depois de renová-la. Nas outras horas, só aparece uma prévia (whsec_...last4). Para trocá-la por uma nova, toque em Renovar chave nas configurações da automação - isso gera uma nova chave HMAC sem mudar a URL nem o cabeçalho de autenticação. A chave antiga para de funcionar na hora.

Só são aceitas URLs HTTPS com nome de domínio. HTTP, endereços IP (públicos ou privados), URLs com nome de usuário ou senha e domínios que apontam para endereços de rede privada são rejeitados. O TellDone confere o endereço de novo a cada envio. Se essa conferência falhar, por exemplo porque o domínio não resolve naquele momento, o envio é interrompido e não é repetido.

Verificar assinaturas de webhook

Todo webhook é assinado para você poder confirmar que ele veio mesmo do TellDone. A assinatura é calculada assim:

HMAC-SHA256(signing_secret, timestamp + "." + raw_body)

O resultado é codificado em hexadecimal e recebe o prefixo sha256= no cabeçalho da assinatura.

Use o corpo bruto da requisição

O TellDone serializa o JSON com espaços depois dos separadores (por exemplo {"event": "note.created"}). Se você interpretar e serializar o corpo de novo, a assinatura não vai coincidir. Verifique sempre com os bytes brutos do corpo da requisição.

Python

import hmac
import hashlib

def verify_signature(raw_body: bytes, signature: str, timestamp: str, secret: str) -> bool:
    payload = f"{timestamp}.".encode() + raw_body
    expected = "sha256=" + hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

# Flask example
@app.route("/webhook/telldone", methods=["POST"])
def telldone_webhook():
    raw_body = request.get_data()  # raw bytes, NOT request.json
    signature = request.headers.get("X-LP-Signature", "")
    timestamp = request.headers.get("X-LP-Timestamp", "")

    if not verify_signature(raw_body, signature, timestamp, SIGNING_SECRET):
        abort(403)

    data = request.json
    # process webhook...

Node.js

const crypto = require("crypto");

function verifySignature(rawBody, signature, timestamp, secret) {
  const payload = `${timestamp}.${rawBody}`;
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(payload).digest("hex");
  const a = Buffer.from(signature);
  const b = Buffer.from(expected);
  // timingSafeEqual throws if the lengths differ, e.g. when the header is missing
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// Express example (use express.raw to get the raw body)
app.post("/webhook/telldone", express.raw({ type: "application/json" }), (req, res) => {
  const rawBody = req.body.toString();
  const signature = req.headers["x-lp-signature"] || "";
  const timestamp = req.headers["x-lp-timestamp"] || "";

  if (!verifySignature(rawBody, signature, timestamp, SIGNING_SECRET)) {
    return res.status(403).send("Invalid signature");
  }

  const data = JSON.parse(rawBody);
  // process webhook...
});

Proteção contra replay (opcional)

Para evitar ataques de replay, confira se o timestamp é recente:

import time

def verify_timestamp(timestamp: str, tolerance_seconds: int = 300) -> bool:
    try:
        return abs(time.time() - int(timestamp)) < tolerance_seconds
    except (ValueError, TypeError):
        return False

Erros comuns

Erro	Correção
Usar o corpo interpretado e serializado de novo	Use o corpo bruto da requisição
JSON.stringify() em JS (compacto, sem espaços)	Use o corpo bruto da requisição
Esquecer o prefixo do timestamp	O formato do payload é timestamp + "." + body
Comparar as strings diretamente	Use hmac.compare_digest ou timingSafeEqual

Política de novas tentativas

Se o seu endpoint falhar, o TellDone repete cada envio neste cronograma:

Tentativa	Espera
1ª nova tentativa	30 segundos
2ª nova tentativa	2 minutos
3ª nova tentativa	15 minutos
4ª nova tentativa	1 hora
5ª nova tentativa	4 horas

Se a 5ª nova tentativa também falhar, o envio é marcado como falho e não é repetido de novo. No app, ele aparece com uma cruz vermelha. Você ainda pode reenviá-lo por conta própria no log completo de envios: abra Todos os envios (o link aparece quando uma automação tem mais de 5 envios) e toque em Tentar novamente no envio que falhou. A lista curta Envios recentes não oferece essa opção.

Como o TellDone trata cada tipo de resposta:

• 2xx - entregue com sucesso
• 4xx (exceto 429) - marcado como falho na hora e não repetido (seu endpoint rejeitou os dados de forma explícita)
• 429 (Too Many Requests) - repetido após o número de segundos indicado em Retry-After (60 segundos, se não houver). Essas repetições não são limitadas a 5, mas cada uma conta para as 20 falhas que desativam a automação
• 5xx ou tempo esgotado - repete no cronograma acima

Quando os envios falham várias vezes

Se os envios continuarem falhando, o TellDone avisa você e, por fim, desativa a automação.

Depois de 3 tentativas com falha: aviso na Caixa de entrada

Depois de 3 tentativas com falha seguidas (as repetições contam também), o TellDone manda uma mensagem para a sua Caixa de entrada com o título Sua automação "Nome" está falhando, com o nome da sua automação entre aspas. Aí você pode abri-la em Configurações > Integrações > Automações, conferir os envios e decidir o que fazer.

Depois de 20 tentativas com falha: desativação automática

Desativação automática

Se 20 tentativas seguidas falharem para a mesma automação (as repetições contam também), o TellDone desativa a automação para ela parar de enviar para um endereço que não está funcionando. Resolva o problema na sua ferramenta de automação e depois reative o botão Ativa em Configurações > Integrações > Automações. Reativá-lo não zera a contagem de falhas, então, até um envio dar certo, uma única tentativa com falha desativa a automação de novo.

Toda tentativa com falha conta, então um envio que falha em todas as 5 novas tentativas soma 6 à contagem. Por isso, uma automação pode se desativar sozinha depois de cerca de 4 envios com falha. O contador volta a zero no próximo envio bem-sucedido.

Gerenciar webhooks

• Ativa - desative este botão para parar uma automação sem excluí-la, e reative quando quiser. Nada é enviado enquanto ele está desativado: as notas e os relatórios desse período não são enviados depois, e os envios que aguardam uma nova tentativa são descartados
• Envios - Envios recentes mostra os últimos 5 com status, código HTTP e tempo de resposta. Quando houver mais, Todos os envios abre o log dos últimos 30 dias, onde você pode filtrar por Todos, Entregues ou Erros e tocar em Tentar novamente em um envio que falhou para reenviá-lo sem esperar a próxima nova tentativa programada
• Testar envio - envia uma nota de exemplo (note.created, com "test": true no corpo), sejam quais forem os tipos de dados escolhidos, sem alterar nenhum dos seus dados. Disponível depois que a automação é salva. Os envios de teste não contam para o seu limite mensal
• Renovar chave - gera uma nova chave secreta HMAC sem mudar a URL nem o cabeçalho de autenticação
• Editar - atualize a URL, o cabeçalho de autenticação, as opções de dados (Nota / Nota + áudio / Tarefas / Eventos / Relatórios) ou os gatilhos (Criado / Atualizado / Concluídas / Excluído). As mudanças valem na hora
• Excluir automação - remove a automação e todos os logs de envio dela de forma permanente

Cada envio mostra o status como um ícone:

Ícone	Significado
Sinal verde de confirmação	Entregue
Relógio amarelo	Aguardando ou sendo enviado
Triângulo vermelho	Falhou, o TellDone vai tentar de novo
Cruz vermelha	Falhou, sem mais novas tentativas automáticas

Você pode tocar em Tentar novamente nos envios com triângulo vermelho ou cruz vermelha no log completo.

Limites de envio

Há dois limites: um limite mensal que depende do seu plano e um limite por hora de 100 envios em todos os planos pagos, que protege contra picos repentinos.

Plano	Automações	Envios por mês	Limite por hora
Free	0	0	-
Basic	1	300	100
Pro	3	3.000	100
Ultra	10	15.000	100

Como os limites funcionam:

• Limite mensal atingido - o envio espera. Ele aparece como falho ("Limite mensal de webhooks excedido") e o TellDone tenta de novo a cada 5 minutos. Ele sai depois que o seu limite é zerado, às 00:00 UTC do dia 1º, a menos que já tenha mais de 30 dias nessa hora. Os envios feitos depois da renovação contam para o novo mês.
• Limite por hora atingido - o envio é adiado e repetido depois de cerca de 5 minutos, então um pico curto não perde dados.

Só os envios bem-sucedidos contam para o limite mensal. O limite por hora conta todas as tentativas, inclusive as novas tentativas. Os envios de teste não contam para nenhum dos dois limites.

Se você mudar de plano, suas automações e as configurações delas são mantidas. No Free, elas param de enviar e você não consegue abri-las até fazer upgrade. No Basic, as automações que você já tinha continuam enviando dentro de 300 envios por mês, mas não dá para adicionar nem ativar mais de uma.

Filtrar eventos de teste

Quando você toca em Testar envio, o payload inclui "test": true no nível principal. Na sua ferramenta de automação, você pode checar esse campo e pular o processamento quando ele estiver presente.

Guias por plataforma

Para instruções passo a passo com a sua ferramenta de automação:

• Zapier - conecte o TellDone a milhares de apps com Zaps
• Make - crie cenários visuais de automação (antigo Integromat)
• n8n - use os webhooks do TellDone em fluxos de trabalho auto-hospedados ou na nuvem
• Endpoints personalizados - qualquer serviço que aceite requisições HTTPS POST funciona com os webhooks do TellDone

Ideias

• Enviar tarefas para uma planilha do Google via Zapier
• Criar mensagens no Slack a partir de notas via Make
• Registrar eventos em um CRM personalizado via n8n
• Fazer backup de todas as notas no armazenamento em nuvem
• Encaminhar relatórios para um painel da equipe

Veja também

• Caixa de entrada e suporte - se um webhook falhar várias vezes, você verá uma mensagem na sua Caixa de entrada
• Zapier - configuração passo a passo do Zapier
• Make - configuração passo a passo do Make
• n8n - configuração passo a passo do n8n
• Todoist - sincronização dedicada de tarefas nos dois sentidos (sem webhooks)
• Notion - integração dedicada com o Notion
• Encaminhamento por email - receba os dados das notas por email