Um webhook envia ao seu servidor cada SMS e cada chamada recebidos no seu número assim que chegam. Desde novembro de 2026, uma chamada curta vem com o texto dela e o código lido nela, então um código de voz chega ao seu código como texto.
Este guia configura o receptor, confere se cada requisição realmente vem de nós e trata os dois tipos de código. Ele pressupõe que você já tem uma chave de API e um número. Se não tiver, comece por automatizar a verificação por SMS com a API.
Por que alguns códigos chegam por chamada
Muitos serviços oferecem “ligue para mim” quando o SMS não chega, e alguns enviam apenas códigos por voz. Um robô lê os dígitos em voz alta. Com um número privado do SMS Activate App, essa chamada chega ao seu número como um SMS.
Toda chamada gravada de até um minuto é transformada em texto quando chega. Você recebe:
- transcript: o que foi dito na chamada, ou null.
- code: o código de verificação lido nela (de 4 a 8 dígitos), ou null.
- transcriptStatus: done, empty (sem fala), failed, toolong (mais de um minuto), overbudget ou off.
O link da gravação funciona por 24 horas. O texto fica guardado.
Passo 1: aponte o número para o seu servidor
Defina o webhook de um número:
O endereço precisa usar HTTPS e responder à nossa verificação com status 2xx antes de ser salvo. Para receber eventos de todos os seus números de uma vez, defina webhookUrl na conta com PATCH /v1/me.
Passo 2: obtenha o segredo de assinatura
A resposta é {"secret": "whsec_..."} e aparece uma única vez. Guarde o segredo junto da sua chave de API. Cada chamada gera um novo segredo, e o antigo deixa de valer na próxima entrega. Por isso, troque o segredo só quando puder atualizar o servidor ao mesmo tempo.
Passo 3: verifique cada requisição
Cada requisição traz três cabeçalhos:
- x-vpn-event: sms.received, call.received, recording.ready, entre outros.
- x-vpn-timestamp: o momento da assinatura, como tempo Unix (segundos).
- x-vpn-signature: v1= seguido de um HMAC-SHA256 em hexadecimal.
A assinatura é um HMAC-SHA256 calculado com o seu segredo sobre v1.<timestamp>.<raw body>. Calcule-a sobre os bytes brutos do corpo, antes de qualquer parse de JSON, e rejeite um timestamp que esteja a mais de cinco minutos do relógio do seu servidor.
Em Node.js com Express:
Responda logo com um 2xx e deixe o trabalho demorado para depois.
Passo 4: pegue o código em qualquer um dos eventos
Um SMS (sms.received):
A gravação de uma chamada (recording.ready, alguns segundos depois do fim da chamada):
Um único handler cobre os dois casos:
Prefira o campo code a extrair o código da transcrição por conta própria: o robô costuma repetir os dígitos ou lê-los um a um, e code já os traz como uma única string.
Passo 5: teste antes do tráfego real
- POST /v1/me/webhook-test envia um evento webhook.test ao seu receptor.
- GET /v1/me/webhook-deliveries lista as últimas entregas: o evento, se foi entregue, o código de status do seu servidor e o número de tentativas.
Se uma entrega falhar, olhe ali primeiro. As causas mais comuns são um segredo errado, um corpo convertido em JSON antes da verificação ou uma resposta lenta.
Sem webhook? Leia as chamadas pela API
Sem servidor, leia as chamadas de um número quando precisar:
Cada chamada traz os mesmos campos transcript, code e transcriptStatus. Na sua conta no site, o código aparece abaixo da chamada e é copiado com um toque.
Quanto custam chamadas e SMS
As chamadas recebidas (por minuto) e os SMS de um número são cobrados do seu saldo a um preço por país, informado como usagePricing (callCents, smsCents, advanceUsd) nos países, nos resultados de busca e nos seus números. Com o saldo zerado, o número continua funcionando até um pequeno adiantamento. Depois disso, as chamadas recebidas são recusadas até você recarregar, e os SMS continuam chegando. Veja os preços.
Próximos passos
- Peça a um agente de programação para montar o receptor: use a API de verificação por SMS com o Claude Code.
- Todas as rotas e campos: documentação da API e o arquivo OpenAPI.
- O que mudou e quando: o changelog da API.