Descripción general
Cómo funcionan los webhooks
- Configura la URL del webhook y selecciona los tipos de eventos
- Quo supervisa los eventos especificados
- Cuando se produce un evento, Quo envía una solicitud POST con la carga útil del evento
- Tu aplicación procesa los datos del evento y responde
- Quo registra el estado de la entrega y vuelve a intentarlo si es necesario
La configuración de webhooks requiere permisos de propietario o administrador del espacio de trabajo. La configuración se gestiona únicamente a través de las aplicaciones web y de escritorio.

Eventos de webhooks disponibles
Eventos de mensajería
message.received: Mensaje de texto recibido en el número de teléfono del espacio de trabajo (incluye archivos multimedia)message.delivered: Mensaje de texto enviado desde el espacio de trabajo y entregado correctamente (incluye archivos multimedia)
call.summary.completed: Resumen de llamada generado por IA disponible en la carga útil del eventocall.transcript.completed: Transcripción completa de la llamada disponible en la carga útil del evento
Eventos de voz
call.ringing: Llamada entrante recibida en el número de teléfono del espacio de trabajocall.completed: Llamada finalizada (contestada o no contestada; puede incluir un buzón de voz)call.recording.completed: Grabación de la llamada disponible en la URL indicada
Eventos de contactos
Administración de contactos:contact.updated: Contacto creado o modificado en el espacio de trabajocontact.deleted: Contacto eliminado del espacio de trabajo
Eventos de tareas
task.created: Tarea creada en tu espacio de trabajotask.updated: Se cambió el título, la descripción, la persona asignada o la fecha límite de la tareatask.completed: Tarea marcada como completadatask.reopened: Tarea completada que se volvió a abrirtask.deleted: Tarea eliminada de tu espacio de trabajotask.unassigned: Se eliminó la persona asignada de la tareatask.due_date_changed: Se cambió la fecha límite de la tareatask.due_date_removed: Se eliminó la fecha límite de la tareatask.overdue: La tarea superó su fecha límitetask.linked: Tarea vinculada a una conversación, un número de teléfono o una actividad de conversacióntask.unlinked: Tarea desvinculada de una conversación
Para obtener más detalles sobre cómo crear integraciones con webhooks y la API, visita la referencia de la API de Quo.
Configurar webhooks
Requisitos de configuración
Parámetros opcionales:
Proceso de configuración
- Ve a Settings → Webhooks en Quo
- Haz clic en Create webhook
- Ingresa la URL del controlador de webhook
- Selecciona los tipos de eventos que deseas monitorear
- Elige los números de teléfono o los recursos de contacto
- Añade una etiqueta opcional para su identificación
- Guarda y prueba la configuración
Creación de controladores de webhook
Requisitos del controlador
- Aceptar solicitudes HTTP POST en tu URL de webhook
- Procesar la carga útil de eventos en formato JSON en el cuerpo de la solicitud
- Responder con un código de estado HTTP 2xx en un máximo de 10 segundos
- Verificar la firma del webhook por seguridad
- Manejar los reintentos y los errores de forma adecuada
- Éxito: Devolver un código de estado 2xx (no se requiere cuerpo de respuesta)
- Error: Una respuesta que no sea 2xx activa la secuencia de reintentos de Quo
- Tiempo de espera: Si no hay respuesta en 10 segundos, se inician reintentos
Seguridad y autenticación
Proceso de verificación de firmas
- Extrae los componentes del encabezado
openphone-signature - Prepara los datos firmados concatenando
timestamp + "." + payload - Decodifica la clave de firma desde base64 (disponible en los detalles del webhook)
- Calcula HMAC-SHA256 usando la clave decodificada y los datos firmados
- Compara el resultado con la firma del encabezado
- Elimina todos los espacios y saltos de línea del JSON
payloadantes de concatenar - Usa la forma binaria de la clave de firma decodificada desde base64 para el cálculo de HMAC
- Asegúrate de que la cadena coincida exactamente para que la verificación sea exitosa
- Ve a la página de detalles del webhook en Quo
- Haz clic en el menú de puntos suspensivos (⋯) en la esquina superior derecha
- Selecciona “Reveal signing secret”
- Copia la clave codificada en base64 para tu aplicación
Ejemplos de implementación
Es posible que en futuras versiones se incluyan varias firmas separadas por comas. Separa el valor del encabezado por comas para manejar múltiples firmas si es necesario.
Mejores prácticas de seguridad
- Compara la marca de tiempo de la firma con la hora actual
- Rechaza las solicitudes con marcas de tiempo fuera del margen de tolerancia aceptable (p. ej., 5 minutos)
- Cada llamada de webhook genera una marca de tiempo y una firma únicas
- Los reintentos incluyen automáticamente nuevas marcas de tiempo
- Usa siempre URL HTTPS para los webhooks de producción
- Almacena las claves de firma de forma segura (variables de entorno, gestión de secretos)
- Implementa una gestión adecuada de errores y del registro de eventos
- Considera aplicar limitación de solicitudes a los endpoints de webhook
Gestión de errores y reintentos
Sistema automático de reintentos
- Condiciones de activación: Códigos de respuesta distintos de 2xx o tiempo de espera de 10 segundos
- Estrategia de backoff: Backoff exponencial con demoras cada vez mayores
- Duración de los reintentos: Hasta 3 días de intentos de reintento
- Fallo final: Se envía una notificación por correo electrónico al creador del webhook
- Los reintentos iniciales se realizan rápidamente para minimizar la demora
- Las demoras aumentan de forma exponencial con cada intento
- Prioriza la entrega lo más cerca posible del momento del evento original
- Seguimiento automático del status durante todo el proceso
Opciones de reintento manual
- Ver el estado de entrega en los detalles del webhook de Quo
- Reintentar manualmente las llamadas de webhook fallidas en cualquier momento
- Los webhooks fallidos se marcan con el estado ‘failure’
- Los reintentos manuales exitosos actualizan el estado a ‘success’
Notificaciones de errores
- Se envía una alerta por correo electrónico al creador del webhook
- La llamada del webhook se marca como error permanente
- Los detalles del evento se conservan para revisión manual
- Opción de reintentar manualmente una vez resueltos los problemas
Pruebas y validación
Pruebas de desarrollo
- Clientes HTTP: Usa cURL, Postman o Insomnia para enviar solicitudes POST de prueba
- URLs locales: Prueba con localhost durante el desarrollo
- Cargas útiles simuladas: Crea JSON de eventos de ejemplo que cumpla con el formato de Quo
- Pruebas de firma: Verifica la lógica de validación HMAC con claves de prueba
Funciones de prueba de Quo
- Ve a la página de detalles del webhook en Quo
- Haz clic en el icono de puntos suspensivos (⋯) en la esquina superior derecha
- Selecciona “Send Test Request”
- Quo envía un evento de muestra a tu URL de webhook
- Verifica la validación de la firma y el manejo de la respuesta
Las solicitudes de prueba requieren URL de webhook accesibles públicamente. Las URL de desarrollo local no funcionan con la función de prueba de Quo.
Pruebas con eventos reales
- Configura el webhook para un tipo de evento específico (p. ej.,
message.received) - Selecciona tu número de Quo en los recursos del webhook
- Activa un evento real (envía un texto a tu número)
- Supervisa la entrega y el procesamiento del webhook
- Verifica el funcionamiento completo de extremo a extremo
- El webhook recibe solicitudes POST correctamente
- La verificación de la firma funciona
- La carga útil del evento se analiza correctamente
- La lógica de la aplicación procesa los eventos correctamente
- Las respuestas de error activan reintentos
- Las respuestas exitosas detienen la secuencia de reintentos
Solución de problemas
Problemas comunes y soluciones
- Verifica que la URL del webhook sea correcta y accesible
- Comprueba que el estado del webhook esté activado en la configuración
- Confirma que los tipos de eventos estén seleccionados correctamente
- Valida que los recursos (números de teléfono/usuarios/grupos) sean correctos
- Códigos de estado HTTP: Asegúrate de devolver respuestas 2xx para indicar un procesamiento correcto
- Tiempo de respuesta: Devuelve las respuestas dentro del tiempo de espera de 10 segundos
- Manejo de errores: Implementa respuestas de error adecuadas para la depuración
- Validación de la firma: Verifica el cálculo de la firma HMAC
- Formato de la clave: Asegúrate de que la clave de firma se haya decodificado correctamente en base64
- Manejo de la marca de tiempo: Comprueba la extracción y concatenación de la marca de tiempo
Herramientas de depuración
- Registro de eventos: Consulta el historial de entrega en la página de detalles del webhook
- Seguimiento del estado: Supervisa las tasas de éxito y error
- Intentos de reintento: Revisa las secuencias automáticas de reintento
- Pruebas manuales: Usa “Send Test Request” para una validación inmediata
- Tiempo de respuesta: Mantén el procesamiento por debajo de 10 segundos
- Tasas de error: Minimiza los fallos para reducir la carga de los reintentos
- Registro: Implementa un registro completo de solicitudes y respuestas
- Monitoreo: Configura alertas para fallos en la entrega de webhooks
Ejemplos de cargas útiles de eventos
Eventos de mensajes
message.received:
message.delivered:
Eventos de llamadas
call.ringing:
call.completed (llamada entrante con buzón de voz):
call.completed (llamada saliente atendida):
call.recording.completed payload:
Eventos de contacto
contact.updated y contact.deleted:
Eventos de análisis de IA
call.summary.completed (payload):
call.transcript.completed:
