Recibir códigos por SMS y por llamada de voz con un webhook: guía de la API

Un webhook envía a tu servidor cada SMS y cada llamada que llega a tu número. Una llamada corta llega con su transcripción y el código que se dicta en ella.

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