Usar Webhooks

SalesMind AI 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 se recibe un mensaje, o se etiqueta una conversación. En lugar de consultar la API, 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 importan y manejar la carga útil.

Requisitos previos

• Una cuenta de SalesMind AI con al menos un sender activo
• Un endpoint HTTPS accesible públicamente que pueda recibir solicitudes POST

Cómo funcionan los webhooks

SalesMind AI dispara un webhook cada vez que ocurre un evento relevante en un hilo de conversación de tu bandeja de entrada — ya sea por una acción de campaña o por un cambio manual que hagas en la interfaz. Cada evento envía una solicitud HTTP POST a la URL que configures.

Tipos de eventos disponibles

Tipo de evento	Se dispara 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 (incluidos mensajes automáticos 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 se quita una etiqueta en un hilo de conversación

Estos cinco eventos activity.* son los que una cuenta normal puede suscribir y recibir. Existe un sexto evento, user.register.v1, pero es solo para administradores — las cuentas normales nunca lo reciben y se elimina automáticamente si intentas suscribirte a él. webhook.test.v1 es un evento único que envía el botón Test, no algo a lo que te suscribes.

Configurar tu endpoint de webhook

1. En la barra lateral izquierda, haz clic en el icono de engranaje Configuración abajo.
2. Haz clic en Webhooks.
3. Pega la URL de tu endpoint HTTPS.
4. Elige los tipos de eventos que quieres recibir.
5. Selecciona de qué agentes quieres recibir eventos.
6. Haz clic en Guardar.

💡 Consejo: Usa el botón Test para enviar una carga útil de ejemplo a tu endpoint. Esto confirma que tu servidor puede recibir solicitudes antes de que se disparen eventos reales.

Gestionar endpoints con la API

Puedes gestionar los endpoints de webhook mediante la API en lugar de la interfaz. Cada endpoint necesita tu encabezado X-API-KEY y está bajo https://api.sales-mind.ai//v1/webhooks.

Método	Endpoint	Propósito
POST	/v1/webhooks/endpoints	Registrar un nuevo endpoint
GET	/v1/webhooks/endpoints	Listar tus endpoints
GET	/v1/webhooks/endpoints/{id}	Obtener un endpoint
DELETE	/v1/webhooks/endpoints/{id}	Eliminar un endpoint
GET	/v1/webhooks/endpoints/{id}/rotate-secret	Obtener un secreto de firma nuevo
PUT	/v1/webhooks/endpoints/{id}/suspend	Suspender o reanudar un endpoint
GET	/v1/webhooks/events	Listar los eventos a los que puedes suscribirte
PUT	/v1/webhooks/endpoints/{id}/events	Cambiar los eventos suscritos
GET	/v1/webhooks/endpoints/{id}/test	Enviar una entrega de prueba

⚠️ El registro no devuelve tu secreto de firma. Después de registrar un endpoint, llama a rotate-secret para obtener el secreto con el que verificas las entregas.

Tu endpoint debe ser una URL HTTPS pública. SalesMind AI lo comprueba cuando entrega un evento, no cuando registras — así que una URL no HTTPS o privada se acepta al principio y luego falla en la entrega.

Entender la carga útil

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	El nombre de tu agente, datos de empresa, servicios, tono de marca y guion de ventas
data.campaign	ID de campaña, nombre, estado, objetivo, URL de página de producto, URL de landing y tipo de campaña
data.campaignContact	Estado del contacto en la campaña (p. ej. invitation_send), detalles de la última actividad y bandera de finalizado
data.threadBox	Nombres completos del sender y del contacto, array de etiquetas, estado de la conversación, fit score, justificación de la IA, nombre de persona y estado de respuesta
data.sender	Perfil completo de LinkedIn de la cuenta que envía, datos de contacto de la base de conocimiento y análisis de personalidad MBTI
data.contact	Perfil de LinkedIn del prospecto, titular, resumen, ubicación, aptitudes, empresas actuales y análisis MBTI
data.messages	Array de mensajes del hilo de conversación

💡 Consejo: La carga útil completa 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 necesitas en tu handler.

Verificar la firma

Cada entrega lleva cuatro encabezados para que confirmes que realmente vino de SalesMind AI:

Encabezado	Valor
Webhook-Signature	HMAC-SHA256 codificado en Base64 de la cadena firmada
Webhook-Timestamp	Segundos de época Unix, usados dentro de la cadena firmada
Webhook-Idempotency-Key	{eventId}:{endpointId} — úsalo para descartar entregas duplicadas
Webhook-Key-Id	current — qué secreto de firma se usó

La cadena firmada es:

{Webhook-Timestamp}.{endpointId}.{sha256_hex(rawBody)}

Firma el valor del encabezado Webhook-Timestamp, no el campo timestamp ISO dentro del cuerpo — son diferentes.

Para verificar una entrega:

1. Lee el cuerpo sin procesar, el encabezado Webhook-Timestamp y el encabezado Webhook-Signature.
2. Calcula el resumen SHA-256 en hex del cuerpo sin procesar y luego construye {Webhook-Timestamp}.{endpointId}.{sha256_hex}.
3. Calcula Base64(HMAC-SHA256(esa cadena, el secreto de tu endpoint)) y compáralo con Webhook-Signature usando una comparación de tiempo constante.
4. Opcionalmente, rechaza la entrega si Webhook-Timestamp es más antiguo que una ventana que elijas (por ejemplo, 5 minutos).

💡 La ventana de reenvío de 5 minutos es una comprobación que añades por tu lado. SalesMind AI no la impone.

⚠️ Después de rotar tu secreto, actualiza tu secreto guardado de inmediato. SalesMind AI siempre firma con el secreto actual, así que las entregas cambian al nuevo secreto al instante — no hay periodo de gracia en el lado de la firma.

Revisar el historial de entregas

Puedes comprobar si un webhook se disparó y revisar su estado de entrega directamente en la app. Ve a Configuración → Webhooks para ver las entregas recientes, sus códigos de estado y marcas de tiempo.

También puedes obtener las entregas mediante la API:

Método	Endpoint	Propósito
GET	/v1/webhooks/deliveries	Listar entregas (filtra por endpointId, status, type)
GET	/v1/webhooks/deliveries/{id}	Obtener una entrega, con su carga útil
POST	/v1/webhooks/deliveries/{id}/replay	Reenviar una entrega como un nuevo evento

Cada entrega tiene un estado: pending, delivered, failed o suspended.

Cómo funcionan los intentos de entrega:

• Cada intento expira tras 5 segundos.
• Una respuesta 2xx marca la entrega como delivered y reinicia el contador de fallos del endpoint.
• Cualquier otra respuesta — o un tiempo de espera agotado — la marca como failed y reintenta con un backoff de 5, 10, 20, 60 y luego 300 segundos (hasta 5 reintentos, es decir, 6 intentos en total).
• Tras 10 fallos consecutivos, SalesMind AI suspende el endpoint automáticamente. Los nuevos eventos para un endpoint suspendido se registran como suspended y se omiten hasta que lo reanudes.

Errores comunes

"La prueba funciona pero los eventos reales no se disparan"

Asegúrate de tener una campaña activa con prospectos avanzando por el flujo. Los webhooks se disparan 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 una etiqueta manualmente. Si no hay actividad, no hay eventos que enviar.

"Recibo eventos pero a la carga útil le faltan campos"

La carga útil varía ligeramente según el tipo de evento. Un evento activity.invitation.sent.v1 no tendrá campos relacionados con respuestas, por ejemplo. Revisa la carga útil de prueba de tu tipo de evento concreto para ver qué campos se incluyen.

"La carga útil es muy grande"

Esto es lo esperado. Cada entrega incluye todo el contexto del agente (servicios, guion de ventas, tono de marca) para que tu handler tenga todo lo necesario para enrutar y procesar el evento. Analiza solo los campos que necesitas.

"Mi URL de endpoint se aceptó pero nunca recibe nada"

Tu endpoint debe ser una URL HTTPS pública. SalesMind AI lo comprueba cuando entrega un evento, no cuando registras — así que una URL no HTTPS o privada se acepta al principio y luego falla en la entrega. Revisa tu historial de entregas en busca de intentos fallidos.

Puntos clave

• Los webhooks envían datos en tiempo real a tu servidor cuando ocurren eventos — tanto acciones automáticas de campaña como cambios manuales.
• Una cuenta normal se suscribe a los cinco eventos activity.*; user.register.v1 es solo para administradores y webhook.test.v1 es solo el evento de prueba.
• Gestiona endpoints, eventos y entregas mediante la API bajo https://api.sales-mind.ai//v1/webhooks — autentícate con X-API-KEY.
• Verifica cada entrega con los encabezados Webhook-Signature y Webhook-Timestamp; el secreto de firma viene de rotate-secret, no del registro.
• Las entregas se reintentan con backoff y un endpoint se suspende tras 10 fallos consecutivos — revisa y reenvía desde el historial de entregas.

FAQ

¿Qué eventos puede recibir mi cuenta? Las cuentas normales reciben los cinco eventos activity.*. user.register.v1 es solo para administradores y webhook.test.v1 es solo el evento de prueba.

¿Cómo verifico que un webhook vino de SalesMind AI? Recalcula la firma a partir del cuerpo sin procesar y el encabezado Webhook-Timestamp, y compárala con el encabezado Webhook-Signature. Consulta "Verificar la firma" más arriba.

¿Cómo obtengo mi secreto de firma? El registro no lo devuelve. Llama al endpoint rotate-secret para obtener un secreto nuevo y actualiza tu copia guardada de inmediato.

¿Por qué se suspendió mi endpoint? SalesMind AI suspende un endpoint tras demasiadas entregas fallidas seguidas — 10 por defecto. Arregla tu servidor y luego reanuda el endpoint.

¿Puedo reenviar un webhook que me perdí? Sí. Usa el endpoint de reenvío para enviar una entrega pasada de nuevo como un nuevo evento.

Mi URL se aceptó pero no llegan eventos. ¿Por qué? La comprobación de HTTPS y URL pública ocurre en el momento de la entrega, no en el registro. Una URL incorrecta se acepta al principio y luego falla en la entrega. Revisa tu historial de entregas.