Webhooks

Eventos de webhook

Também existem dois eventos de serviço: endpoint.verification (enviado na criação e quando a URL muda; responda com 2xx para ativar o endpoint) e endpoint.test (enviado quando você clica em "Enviar evento de teste" no console ou chama a API de teste).

Corpo da requisição

Webhooks são notificações enxutas: carregam identificadores e status, nunca o conteúdo da transcrição ou do resumo. Busque o conteúdo na API REST usando o note_id.

{
  "event_id": "5f8c0a5e-...",
  "event_type": "note.ended",
  "occurred_at": "2026-08-12T05:20:00Z",
  "data": {
    "note_id": "note_abc123",
    "recording_session_id": "rec_456",
    "revision": 7,
    "transcript_status": "ready",
    "summary_status": "pending"
  }
}

Verificar assinaturas

As entregas são assinadas conforme a especificação Standard Webhooks, com o segredo whsec_... emitido na criação do endpoint:

POST /webhooks/alt HTTP/1.1
Content-Type: application/json
webhook-id: 5f8c0a5e-...
webhook-timestamp: 1765515600
webhook-signature: v1,K5oZfzN95Z9UVu1EsPQmSmZQGGVfCM0jaZ0lPI4dvLU=

signed_content = "{webhook-id}.{webhook-timestamp}.{raw request body}"
signature     = base64( HMAC-SHA256( base64url_decode(secret_after_whsec_), signed_content ) )

• Verifique sobre o corpo bruto (raw body) da requisição — não serialize o JSON novamente.
• Compare as assinaturas com uma comparação em tempo constante.
• Rejeite timestamps antigos (recomendamos uma tolerância de ±5 minutos) para evitar ataques de replay.
• Rejeite com 4xx as requisições cuja assinatura não confere. Código de receptor funcionando: passo 4 do Início rápido.

Falhas de entrega e novas tentativas

• Responda com 2xx em até 10 segundos. Qualquer outra coisa conta como falha. Confirme primeiro e processe de forma assíncrona.
• Entregas com falha são repetidas com backoff crescente (30s → 5min → 30min → 2h → 12h → 12h, até 7 tentativas no total).
• Um endpoint que falha em muitas entregas consecutivas é desativado automaticamente.
• Redirecionamentos não são seguidos; a URL do webhook precisa responder diretamente via HTTPS.

Tratar eventos duplicados

A entrega é at-least-once: o mesmo evento pode chegar mais de uma vez (retentativas, reenvios pelo console). Guarde por um curto período os event_id já processados e ignore as duplicatas.

Tratar eventos fora de ordem

Os eventos podem chegar fora de ordem (retentativas, entregas paralelas). Não presuma que o último a chegar é o estado mais recente. Toda mudança visível externamente incrementa a revision da nota (atribuída pelo servidor, monotônica): guarde por nota a revision que você já aplicou e ignore qualquer evento com revision igual ou menor. Na dúvida, busque a nota novamente na API REST — ela sempre retorna a revision atual.

Verificar mudanças perdidas

• Webhooks podem ser perdidos (indisponibilidade maior que a janela de retentativas, endpoints desativados). Chame GET /v1/notes?updated_after=<last sync> periodicamente para se atualizar.
• note.deleted com reason: "access_lost" significa que a nota saiu do escopo da sua credencial (por exemplo, uma nota pessoal movida para um espaço de equipe). Trate exatamente como uma exclusão: remova ou bloqueie o acesso à sua cópia armazenada.
• Só o polling incremental não detecta exclusões nem perda de acesso. Liste todas as notas periodicamente (com include_deleted=true para ver as tombstones): qualquer ID de nota que você tenha e que não apareça mais na listagem foi excluído ou saiu do seu escopo.