QuantumOutbound puede enviar datos de eventos a tu servidor en el momento en que algo sucede — se envía una solicitud de conexión, un prospecto acepta, se envía o recibe un mensaje, o se etiqueta una conversación. En lugar de consultar la API constantemente, tu endpoint recibe una solicitud POST con todo el contexto.
Esta guía te muestra cómo configurar un endpoint de webhook, elegir los eventos que te interesan y manejar el payload.
Requisitos previos
- Una cuenta de QuantumOutbound con al menos un remitente activo
- Un endpoint HTTPS accesible públicamente que pueda recibir solicitudes POST
Cómo funcionan los webhooks
QuantumOutbound activa un webhook cada vez que ocurre un evento relevante en un hilo de conversación en tu bandeja de entrada — ya sea por una acción de campaña o por un cambio manual que realices en la interfaz. Cada evento envía una solicitud HTTP POST a la URL que hayas configurado.
Tipos de eventos disponibles
| Tipo de evento | Se activa cuando… |
|---|---|
activity.invitation.sent.v1 | Se envía una solicitud de conexión a un prospecto |
activity.connection.accepted.v1 | Un prospecto acepta tu solicitud de conexión |
activity.message.sent.v1 | Se envía un mensaje a un prospecto (incluyendo mensajes automatizados de campaña y seguimientos) |
activity.message.received.v1 | Un prospecto responde a tu conversación |
activity.threadbox.tags.update.v1 | Se añade o elimina una etiqueta en un hilo de conversación |
Configurar tu endpoint de webhook
- En la barra lateral izquierda, haz clic en el icono de Configuración (engranaje) en la parte inferior.
- Haz clic en Webhooks.
- Pega la URL de tu endpoint HTTPS.
- Elige los tipos de eventos que deseas recibir.
- Selecciona de qué agentes quieres recibir eventos.
- Haz clic en Guardar.
💡 Consejo: Usa el botón Test para enviar un payload de ejemplo a tu endpoint. Esto confirma que tu servidor puede recibir solicitudes antes de que se activen eventos reales.
Entender el payload
Cada entrega de webhook envía un objeto JSON con tres campos de nivel superior y un objeto data anidado que contiene todo el contexto.
Campos de nivel superior:
| Campo | Descripción | Ejemplo |
|---|---|---|
id | ID único de entrega (usado como clave de idempotencia) | df313559-7cb1-... |
type | El tipo de evento | activity.connection.accepted.v1 |
timestamp | Cuándo ocurrió el evento (ISO 8601) | 2026-02-06T05:05:36+01:00 |
El objeto data contiene estas secciones:
| Sección | Qué contiene |
|---|---|
data.agent | Nombre de tu agente, detalles de la empresa, servicios, tono de marca y playbook de ventas |
data.campaign | ID de campaña, nombre, estado, objetivo, URL de página de producto, URL de landing page y tipo de campaña |
data.campaignContact | Estado del contacto en la campaña (ej. invitation_send), detalles de última actividad e indicador de terminación |
data.threadBox | Nombres completos del remitente y contacto, array de etiquetas, estado de la conversación, puntuación de compatibilidad, razonamiento IA, nombre del persona y estado de respuesta |
data.sender | Perfil completo de LinkedIn de la cuenta remitente, info de contacto de la base de conocimiento y análisis de personalidad MBTI |
data.contact | Perfil de LinkedIn del prospecto, titular, resumen, ubicación, habilidades, empresas actuales y análisis MBTI |
data.messages | Array de mensajes en el hilo de conversación |
Cabeceras de seguridad incluidas en cada entrega:
| Cabecera | Descripción |
|---|---|
webhook-signature | Firma HMAC para verificar que la solicitud proviene de QuantumOutbound |
webhook-timestamp | Marca de tiempo Unix de cuándo se envió el payload |
webhook-idempotency-key | Clave única para evitar el procesamiento de entregas duplicadas |
webhook-key-id | Identifica qué clave de firma se utilizó |
💡 Consejo: El payload completo es grande e incluye todo el contexto del agente. Envía primero un webhook de prueba a tu endpoint y luego usa ese JSON para mapear solo los campos que necesites en tu handler.
Consultar el historial de entregas
Puedes verificar si un webhook se activó y revisar su estado de entrega directamente en la aplicación. Ve a Configuración → Webhooks para ver las entregas recientes, sus códigos de estado y marcas de tiempo.
Errores comunes
"El test funciona pero los eventos reales no se activan"
Asegúrate de tener una campaña activa con prospectos avanzando en el flujo de trabajo. Los webhooks se activan cuando el sistema realiza una acción (envía una invitación, envía un mensaje, recibe una respuesta, etiqueta un hilo) o cuando cambias manualmente una etiqueta. Si no hay actividad, no hay eventos que enviar.
"Recibo eventos pero faltan campos en el payload"
El payload varía ligeramente según el tipo de evento. Un evento activity.invitation.sent.v1 no tendrá campos relacionados con respuestas, por ejemplo. Revisa el payload de prueba para tu tipo de evento específico para ver qué campos están incluidos.
"El payload es muy grande"
Esto es normal. Cada entrega incluye el contexto completo del agente (servicios, playbook de ventas, tono de marca) para que tu handler tenga todo lo necesario para enrutar y procesar el evento. Parsea solo los campos que necesites.
Puntos clave
- Los webhooks envían datos en tiempo real a tu servidor cuando ocurren eventos — tanto acciones automatizadas de campaña como cambios manuales.
- Cinco tipos de eventos cubren todo el ciclo de prospección: invitación enviada, conexión aceptada, mensaje enviado, mensaje recibido y etiqueta actualizada.
- El payload incluye el contexto completo del agente, campaña y contacto en una estructura JSON anidada.
- Las cabeceras de seguridad te permiten verificar que cada entrega proviene de QuantumOutbound.
- Comienza con un webhook de prueba para capturar la estructura completa del payload antes de desarrollar tu handler.