Automações com webhooks

Plano Basic e superiores

Webhooks exigem um plano pago. Basic: 1 webhook, Pro: 3, Ultra: 10.

Webhooks permitem conectar o TellDone a qualquer serviço externo. Quando você cria uma nota de voz, o TellDone processa e envia automaticamente os dados extraídos - notas, tarefas, eventos e relatórios - para uma URL que você indicar. Cada tarefa e evento é enviado como uma entrega separada, então sua ferramenta de automação pode tratá-los individualmente.

Escolhendo o que enviar

Cada automação tem seus próprios interruptores de payload. Escolha um ou qualquer combinação:

• Notas - a nota processada completa (título, transcrição, resumo, tags, idioma)
• Áudio - no plano Ultra, anexe um link de download de 24 horas para o arquivo de áudio junto com o payload da nota
• Tarefas - uma entrega por tarefa extraída
• Eventos - uma entrega por evento de calendário extraído
• Relatórios - uma entrega por relatório diário, semanal, mensal ou anual gerado

Você pode mudar os interruptores a qualquer momento nas configurações da automação - as mudanças se aplicam apenas a novos eventos.

Configurando um webhook

1. Vá em Configurações > Integrações > Automações com webhooks
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: notas, tarefas, eventos, relatórios (ou qualquer combinação)
6. Opcionalmente, adicione um cabeçalho de autenticação - um token enviado como cabeçalho Authorization para endpoints seguros
7. Toque em Salvar
8. Copie o segredo de assinatura - ele é mostrado completo apenas quando você cria a automação pela primeira vez ou depois de rotacioná-lo. Você vai precisar dele se quiser verificar a autenticidade do webhook
9. Toque em "Testar" para enviar um payload de exemplo ao seu endpoint sem criar um evento real

dica

A URL do webhook deve usar HTTPS. Endereços HTTP e IPs de rede privada não são aceitos.

O que é enviado

Cada entrega é um objeto JSON com três campos: event (o tipo de evento), timestamp e data (o conteúdo em si). Aqui está como cada tipo de evento aparece.

Notas (note.created)

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

{
  "event": "note.created",
  "timestamp": "2026-02-27T14:38:00Z",
  "data": {
    "note_id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Notas da reunião - Projeto Alpha",
    "transcript": "Texto completo da transcrição...",
    "summary": "Resumo curto gerado por IA...",
    "type": "meeting",
    "tags": ["work", "project-alpha"],
    "priority": "high",
    "language": "en",
    "created_at": "2026-02-27T10:00:00Z"
  }
}

No plano Ultra, as entregas 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" ao criar a automação.

Tarefas (task.created)

Uma entrega por tarefa. Uma única nota com 3 tarefas envia 3 webhooks separados.

{
  "event": "task.created",
  "timestamp": "2026-02-27T14:38:01Z",
  "data": {
    "note_id": "550e8400-...",
    "note_title": "Notas da reunião - Projeto Alpha",
    "task_id": "660f9511-...",
    "title": "Enviar proposta para o cliente",
    "description": "Incluir preços do Q2",
    "priority": "high",
    "due_date": "2026-03-01",
    "reminder_at": "2026-02-28T09:00:00Z",
    "tags": ["work"],
    "status": "todo",
    "created_at": "2026-02-27T10:00:00Z"
  }
}

Eventos (calendar_event.created)

Uma entrega por evento de calendário.

{
  "event": "calendar_event.created",
  "timestamp": "2026-02-27T14:38:02Z",
  "data": {
    "note_id": "550e8400-...",
    "note_title": "Notas da reunião",
    "event_id": "770a0622-...",
    "title": "Daily do time",
    "description": "Sync semanal",
    "start": "2026-03-03T10:00:00+03:00",
    "end": "2026-03-03T10:30:00+03:00",
    "location": "Zoom",
    "is_all_day": false,
    "attendees": ["alice@example.com"],
    "tags": ["work"],
    "created_at": "2026-02-27T10:00:00Z"
  }
}

Relatórios (report.created)

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

{
  "event": "report.created",
  "timestamp": "2026-02-28T00:05:00Z",
  "data": {
    "report_id": "880b1733-...",
    "report_type": "daily",
    "period_start": "2026-02-27",
    "period_end": "2026-02-27",
    "content_md": "# Relatório diário\n\n...",
    "content_json": {
      "productivity_score": 72,
      "day_type": "productive",
      "tasks_created": 5,
      "tasks_completed": 3
    },
    "created_at": "2026-02-28T00:05:00Z"
  }
}

Segurança

Cada entrega é assinada com HMAC-SHA256 usando o segredo de assinatura da sua automação. Os cabeçalhos a seguir são incluídos em cada entrega:

• X-LP-Signature - a assinatura HMAC-SHA256 (sha256=...)
• X-LP-Timestamp - timestamp Unix usado para assinar
• X-LP-Event - o tipo de evento (note.created, task.created, calendar_event.created, report.created)
• X-LP-Delivery-Id - ID único da entrega (útil para deduplicação)
• User-Agent - sempre TellDone-Webhooks/1.0

Os cabeçalhos de assinatura são enviados em toda entrega, independentemente de outras configurações.

Por padrão, toda entrega inclui o segredo de assinatura da sua automação no cabeçalho Authorization - então ferramentas como o Header Auth do n8n funcionam de imediato colando o segredo como valor de autenticação. Se você definir um cabeçalho de autenticação personalizado nas configurações, ele substitui esse padrão. Você pode usar dois formatos: Nome-do-Cabeçalho: valor (envia o cabeçalho nomeado) ou um valor simples (envia como Authorization: <valor>).

Cada automação tem seu próprio segredo de assinatura, então rotacionar um não afeta nenhum dos outros webhooks. O segredo é mostrado completo apenas quando você cria a automação pela primeira vez ou depois de rotacioná-lo. Em outros momentos, apenas um preview (whsec_...últimas4) é exibido. Para trocar por um novo, toque em "Rotacionar segredo" nas configurações da automação - isso gera uma nova chave HMAC sem mudar a URL ou o cabeçalho de autenticação. O segredo antigo para de funcionar imediatamente.

Apenas URLs HTTPS são aceitas. HTTP, endereços de IP e endereços de rede privada são rejeitados.

Verificando assinaturas de webhook

Verifique o HMAC

Cada entrega inclui um cabeçalho de assinatura no formato X-LP-Signature: sha256=<hex>. O exemplo abaixo mostra como verificar em Python.

Cada webhook é assinado para você confirmar que veio mesmo do TellDone. A assinatura é calculada como:

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

O resultado é codificado em hex e prefixado com sha256= no cabeçalho de assinatura.

Use o corpo bruto da requisição

O TellDone serializa JSON com espaços após separadores (por exemplo, {"event": "note.created"}). Se você fizer parse e re-serializar o corpo, a assinatura não vai bater. Sempre verifique contra 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)

# Exemplo Flask
@app.route("/webhook/telldone", methods=["POST"])
def telldone_webhook():
    raw_body = request.get_data()  # bytes brutos, NÃO 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
    # processar 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");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Exemplo Express (use express.raw para obter o corpo bruto)
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("Assinatura inválida");
  }

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

Proteção contra replay (opcional)

Para prevenir ataques de replay, verifique 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 corpo parseado + re-serializado	Use o corpo bruto da requisição
JSON.stringify() em JS (compacto, sem espaços)	Use o corpo bruto ou combine o espaçamento do Python
Esquecer o prefixo de timestamp	O formato do payload é timestamp + "." + body
Comparar strings diretamente	Use hmac.compare_digest ou timingSafeEqual

Política de novas tentativas

Se seu endpoint falha, o TellDone tenta cada entrega de novo com backoff exponencial (alguns minutos, depois intervalos maiores):

Tentativa	Atraso
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

Após 5 tentativas falhas, a entrega é marcada como morta. Você ainda pode tentar manualmente pelo Log de entregas.

Como o TellDone trata diferentes respostas:

• 2xx - entregue com sucesso
• 4xx (exceto 429) - marcada como morta imediatamente, sem nova tentativa (seu endpoint rejeitou explicitamente os dados)
• 429 (Too Many Requests) - tenta de novo, respeita o cabeçalho Retry-After
• 5xx ou timeout - tenta de novo conforme a programação acima

Quando entregas falham repetidamente

Você não precisa ficar de olho no Log de entregas para saber quando algo está quebrado. O TellDone monitora falhas consecutivas para você e avisa em duas etapas.

Após 3 falhas: aviso na Caixa de entrada

Após 3 entregas falhas consecutivas, o TellDone cria uma mensagem na sua Caixa de entrada na categoria "Falhas de webhook". A mensagem nomeia a automação afetada e te leva direto para Configurações > Integrações > Automações > [a automação com falha] > Log de entregas para você inspecionar a resposta e decidir o que fazer.

dica

Alertas na Caixa de entrada significam que você descobre automações quebradas pelo selo no ícone do app, em vez de descobrir semanas depois por dados faltando na sua ferramenta de destino.

Após 20 falhas: desativação automática

Desativação automática

Se 20 entregas consecutivas para a mesma automação falham (contadas após o aviso na Caixa de entrada), o TellDone desativa a automação automaticamente para parar de bater num endpoint quebrado e proteger sua cota mensal de entregas. Conserte o problema no destino e reative a automação em Configurações > Integrações > Automações.

O contador de falhas consecutivas zera na próxima entrega bem-sucedida.

Gerenciando webhooks

• Pausar/retomar - desative qualquer automação sem excluir, reative quando quiser
• Log de entregas - veja todas as entregas com status, código HTTP e tempo de resposta. Filtre por Entregue ou Erros. Toque em qualquer entrega falha e escolha "Tentar novamente" para reenviar sem esperar a próxima nova tentativa programada
• Testar - toque em "Testar" para enviar um payload de exemplo (com "test": true no corpo) ao seu endpoint sem criar um evento real. Envios de teste não contam contra sua cota mensal
• Rotacionar segredo - gere um novo segredo de assinatura HMAC sem mudar a URL ou o cabeçalho de autenticação
• Editar - atualize URL, cabeçalho de autenticação ou interruptores de payload (notas / áudio / tarefas / eventos / relatórios). As mudanças têm efeito imediato
• Excluir - remove permanentemente a automação e todos os seus logs de entrega

Limites de entrega

A entrega de webhooks tem dois limites: uma cota mensal (limite rígido, varia por plano) e um limite anti-rajada por hora (limite flexível, idêntico em todos os planos pagos).

Plano	Webhooks	Entregas mensais	Rajada por hora
Free	0	0	-
Basic	1	300	100
Pro	3	3.000	100
Ultra	10	15.000	100

O plano Ultra também suporta links de áudio nos payloads de nota (validade de 24 horas).

Como os limites se comportam:

• Cota mensal excedida: a entrega é marcada como falha sem nova tentativa. Novas entregas voltam no dia 1º do mês seguinte, quando o contador é reiniciado.
• Limite por hora excedido: a entrega é adiada e tentada novamente em cerca de 5 minutos, assim uma rajada curta não perde dados. É uma proteção anti-rajada flexível, não uma rejeição definitiva.

Envios de teste e reenvios manuais do registro de entregas não contam para nenhum dos dois limites.

Filtrando eventos de teste

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

Guias por plataforma

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

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

Casos de uso populares

• Enviar tarefas para um Google Sheets 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 para armazenamento em nuvem
• Encaminhar relatórios para um dashboard do time

Veja também

• Caixa de entrada e suporte - se um webhook falha repetidamente, 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 em mão dupla (sem webhooks)
• Notion - integração dedicada com o Notion
• Encaminhamento por e-mail - receba dados de nota por e-mail