Un webhook envía a tu servidor cada SMS y cada llamada que llega a tu número, en cuanto llega. Desde noviembre de 2026, una llamada corta viene con su transcripción y el código que se dicta en ella, así que tu programa también recibe los códigos de voz como texto.
En esta guía configuras el receptor, compruebas que cada petición viene realmente de nosotros y gestionas los dos tipos de código. Damos por hecho que ya tienes una clave de API y un número; si no, empieza por automatizar la verificación por SMS con la API.
Por qué algunos códigos llegan por llamada
Muchos servicios ofrecen «recibir una llamada» cuando un SMS no llega, y algunos solo envían códigos de voz. Un robot dicta los dígitos. Con un número privado de SMS Activate App, esa llamada llega a tu número igual que un SMS.
Cada llamada grabada de hasta un minuto se transcribe a texto al recibirse. Obtienes:
- transcript: lo que se dijo en la llamada, o null.
- code: el código de verificación dictado en ella (de 4 a 8 dígitos), o null.
- transcriptStatus: done, empty (sin voz), failed, toolong (más de un minuto), overbudget u off.
El enlace de la grabación funciona durante 24 horas. El texto se conserva.
Paso 1: apunta el número a tu servidor
Configura el webhook de un número:
La dirección debe usar HTTPS y responder a nuestra comprobación con un estado 2xx antes de guardarse. Para recibir los eventos de todos tus números a la vez, configura en su lugar webhookUrl en la cuenta con PATCH /v1/me.
Paso 2: obtén el secreto de firma
La respuesta es {"secret": "whsec_..."} y se muestra una sola vez. Guárdalo junto a tu clave de API. Cada vez que haces esta petición se genera un secreto nuevo y el anterior deja de valer en la siguiente entrega, así que rótalo solo cuando puedas actualizar tu servidor al mismo tiempo.
Paso 3: verifica cada petición
Cada petición lleva tres cabeceras:
- x-vpn-event: sms.received, call.received, recording.ready y otros.
- x-vpn-timestamp: el momento de la firma, como marca de tiempo Unix (segundos).
- x-vpn-signature: v1= y un HMAC-SHA256 en hexadecimal.
La firma es un HMAC-SHA256 con tu secreto sobre v1.<timestamp>.<raw body>. Calcúlala sobre los bytes sin procesar, antes de parsear el JSON, y rechaza una marca de tiempo que se desvíe más de cinco minutos de tu reloj.
En Node.js con Express:
Responde rápido con un 2xx y deja el trabajo pesado para después.
Paso 4: toma el código de cualquiera de los dos tipos de evento
Un SMS (sms.received):
La grabación de una llamada (recording.ready, unos segundos después de que termine la llamada):
Un solo manejador cubre ambos:
Usa el campo code en lugar de analizar tú mismo la transcripción: el robot suele repetir los dígitos o dictarlos uno a uno, y code ya los contiene como una sola cadena.
Paso 5: pruébalo antes del tráfico real
- POST /v1/me/webhook-test envía un evento webhook.test a tu receptor.
- GET /v1/me/webhook-deliveries lista las últimas entregas: el evento, si se entregó, el código de estado de tu servidor y el número de intentos.
Si una entrega falla, mira primero ahí: las causas habituales son un secreto incorrecto, un cuerpo parseado antes de la comprobación o una respuesta lenta.
¿Sin webhook? Lee las llamadas con la API
Si no tienes servidor, lee las llamadas de un número cuando las necesites:
Cada llamada incluye los mismos campos transcript, code y transcriptStatus. En tu cuenta del sitio web, el código aparece debajo de la llamada y se copia con un toque.
Cuánto cuestan las llamadas y los SMS
Las llamadas entrantes (por minuto) y los SMS de un número se cobran de tu saldo con un precio por país, que se devuelve como usagePricing (callCents, smsCents, advanceUsd) en los países, los resultados de búsqueda y tus números. Con el saldo a cero, un número sigue funcionando hasta un pequeño adelanto; una vez superado, se rechazan las llamadas entrantes hasta que recargues, y los SMS siguen llegando. Consulta los precios.
Siguientes pasos
- Deja que un agente de programación construya el receptor: usar la API de verificación por SMS con Claude Code.
- Todas las rutas y campos: la documentación de la API y el archivo OpenAPI.
- Qué cambió y cuándo: el registro de cambios de la API.