API e webhooks: primeiros passos

A API pública deixa suas automações lerem números, chamadas e SMS da sua conta, e os webhooks avisam a sua aplicação assim que algo acontece. Tudo começa na área Desenvolvedores, no menu lateral.

Visão geralCopiar enlace

A aba Visão geral resume o que já existe na conta:

• Tokens ativos, com a data do último uso.
• Webhooks ativos, dentro do limite da conta.
• Entregas com falha seguidas.
• Escopos concedidos, somando os tokens ativos.

O cartão Comece aqui marca cada passo concluído, e ao lado ficam os limites da sua conta e os links da documentação (OpenAPI JSON, guia em Markdown, arquivo para agentes de IA e a referência das rotas).

1. Crie um tokenCopiar enlace

1. Abra a aba Tokens.
2. Em Nome, escreva algo que lembre onde ele será usado, por exemplo automação n8n.
3. Em Permissões, marque só o que a automação precisa: Ler DIDs, Ler encaminhamentos, Alterar encaminhamentos, Ler chamadas, Ler SMS e Enviar SMS.
4. Clique em Criar token.

O valor completo aparece uma única vez, no momento da criação. Depois disso nem nós conseguimos exibi-lo: se perder, use Rotacionar.

Na lista você vê nome, permissões, último uso e estado, e pode Rotacionar (gera um valor novo) ou Revogar (desliga o token na hora).

2. Faça a primeira chamadaCopiar enlace

O passo 2 da visão geral traz um comando pronto, com o botão de copiar ao lado: um curl para a rota /api/v1/me, com o cabeçalho Authorization: Bearer e o seu token. Copie, troque a variável pelo token e rode no terminal.

Se a resposta vier com os dados da sua conta, o token está funcionando. Só então monte o resto da automação.

3. Receba eventos com webhooksCopiar enlace

1. Abra a aba Webhooks e clique em Novo webhook.
2. Dê um nome, informe a URL do seu endpoint (HTTPS em produção) e escolha os eventos.
3. Se quiser, use o filtro de número para receber só de DIDs específicos.
4. Salve. O segredo de assinatura aparece uma única vez: guarde na hora.

Cada endpoint mostra o estado, último sucesso, última falha e falhas seguidas. Em Entregas, cada envio aparece com evento, status, código HTTP, número de tentativas e a resposta do seu servidor; Tentativas abre o detalhe de cada uma.

Como identificar e validar o eventoCopiar enlace

A requisição chega com cabeçalhos próprios, entre eles o tipo do evento, o id da entrega, o timestamp e a assinatura. O corpo JSON é assinado em HMAC-SHA256 sobre timestamp + payload bruto: calcule e compare com o cabeçalho de assinatura antes de confiar no conteúdo.

Como tratamos falhasCopiar enlace

• Não seguimos redirects.
• Bloqueamos hosts locais, IPs privados e redes reservadas.
• Depois de várias falhas seguidas, o endpoint é pausado e avisamos você.

LimitesCopiar enlace

A aba Visão geral mostra os limites da sua conta: leitura, escrita, envio de SMS (por minuto e por dia) e quantidade de webhooks. Respostas 429 trazem o cabeçalho Retry-After e os cabeçalhos X-RateLimit: espere o tempo indicado antes de tentar de novo.

Boas práticasCopiar enlace

• Trate o token como senha: fora do código, em variável de ambiente ou cofre.
• Um token por automação, com o mínimo de permissões — assim dá para revogar um sem derrubar os outros.
• Rotacione ao menor sinal de vazamento.
• Valide sempre a assinatura do webhook e responda rápido, processando o trabalho pesado depois.

Dúvidas comunsCopiar enlace

• Perdi o token. Não é possível vê-lo de novo. Use Rotacionar para gerar um valor novo, ou Revogar e criar outro.
• Recebo 401. O token foi revogado, está incompleto, ou falta o prefixo Bearer no cabeçalho.
• Recebo 403. O token não tem o escopo daquela rota. Crie um token com a permissão que falta.
• O webhook parou de receber. Verifique se o endpoint foi pausado por falhas seguidas e olhe a coluna Erro/Resposta em Entregas.
• Meu endpoint é HTTP. Use HTTPS em produção: é o esperado pela integração.