Sign inGet Started

URL de callback de SMS

Una URL de callback recibe los eventos de un mensaje de SMS, o de todos los mensajes de un perfil de mensajería, en lugar de tus endpoints de webhook. Úsala cuando un mensaje o un programa necesite su propio receptor.

Gestiona el secreto de firma, el historial de intentos y el reenvío en el panel, o mediante la API y los comandos bird webhooks callbacks. Define la URL de un perfil cuando crees un perfil de mensajería o lo actualices.

Elige adónde van los eventos

La URL se determina una sola vez, cuando se acepta el mensaje, y se conserva durante toda la vida del mensaje. Si cambias el perfil después, los mensajes en curso no cambian de destino.

MensajeURL utilizada
Enviado con options.callback_urlEsa URL
Enviado con options.callback_url definido como nullNinguna: los eventos van a tus endpoints de webhook
Enviado sin ella, en un perfil de mensajeríaLa options.callback_url del perfil
Recibido en un número de un perfil de mensajeríaLa inbound.callback_url del perfil y, si no existe, su options.callback_url
Ninguna URL de las anterioresNinguna: los eventos van a tus endpoints de webhook

La URL debe ser HTTPS, tener como máximo 2048 caracteres y apuntar a una dirección pública. Un host privado, de loopback o de enlace local devuelve 422.

La lista de intentos de callback muestra adónde se entregó el evento de un mensaje recibido.

Qué sustituye la URL

Mientras se aplica una URL, los eventos de ese mensaje no pasan por tus endpoints de webhook. Los demás mensajes del espacio de trabajo siguen llegando a ellos. Si un callback falla, los eventos no se envían a tus endpoints como alternativa: usa el reenvío para recuperarlo.

Las suscripciones de MCP Events y los endpoints de conectores siguen recibiendo los eventos del mensaje.

Los callback_events de un perfil de mensajería eligen qué eventos salientes van a la URL, entre sms.accepted, sms.sent, sms.delivered, sms.undelivered, sms.failed, sms.rejected y sms.expired. Un evento que la lista excluye tampoco llega a ningún endpoint de webhook para ese mensaje. Un perfil sin lista y un envío sin perfil entregan todos los eventos salientes. sms.received nunca se filtra. Los payloads son los eventos de SMS.

Verifica las firmas

Los callbacks usan los mismos encabezados de Standard Webhooks y la misma firma HMAC-SHA256 que los endpoints de webhook, así que el código de verificación de firmas que ya tienes funciona sin cambios. La clave es el secreto de firma de callbacks de tu espacio de trabajo, un único secreto que comparten todas las URL de callback y todas las solicitudes de webhook de secuencias de voz, por lo que una rotación afecta a ambos.

El primer secreto nunca se muestra. Rótalo para obtener uno que puedas usar, en Webhooks → Direct callbacks en el panel o con Rotate callback signing secret. El nuevo secreto aparece una sola vez, así que guárdalo antes de salir de la página. Durante las 24 horas siguientes, cada callback se firma con el secreto antiguo y con el nuevo, para que puedas desplegar el nuevo sin perder entregas. Un espacio de trabajo puede tener como máximo 5 secretos válidos a la vez, por lo que una nueva rotación durante ese periodo puede rechazarse. Una rotación se aplica en aproximadamente un minuto.

Rota el secreto antes de depender de la verificación: hasta que lo hagas, los callbacks llevan una firma hecha con un secreto que no puedes leer.

Reintentos y duplicados

Las devoluciones de llamada siguen el calendario de reintentos de los endpoints de webhook: ocho intentos a lo largo de unas 27,5 horas, y una respuesta 2xx en menos de 15 segundos cuenta como éxito. A diferencia de un endpoint, una URL de devolución de llamada nunca se pausa.

La entrega se produce al menos una vez y sin orden garantizado. Elimina los duplicados con el encabezado webhook-id y ordena por el campo timestamp del payload.

Encuentra y reenvía los callbacks fallidos

La pestaña Direct callbacks de Webhooks en el panel y List callback delivery attempts muestran los intentos de callback del espacio de trabajo, del más reciente al más antiguo, con la URL, el estado que devolvió tu receptor y la latencia. Los intentos se conservan durante tres días.

Replay failed callback deliveries pone en cola un intento más para cada evento cuyos callbacks fallaron en el intervalo de tiempo que elijas, igual que el reenvío de entregas a endpoints hace con los endpoints. Se omite un evento que también se entregó correctamente dentro de ese intervalo. Un éxito fuera del intervalo no cuenta, así que ese evento se vuelve a enviar. Un reenvío envía como máximo los 10.000 eventos fallidos más antiguos del intervalo; tras una interrupción más larga, vuelve a reenviar con una hora de inicio posterior para el resto.

Un reenvío se dirige a la URL registrada en los intentos fallidos, no a tus endpoints de webhook ni a la URL actual del perfil. Sirve para recuperarte de una interrupción en tu receptor. No recupera un mensaje enviado a una URL incorrecta; en ese caso, vuelve a enviar el mensaje. Los reenvíos cuentan para el mismo límite diario que los reenvíos a endpoints.

Próximos pasos