Webhooks Los webhooks te permiten recibir notificaciones HTTP en tiempo real cuando ocurren eventos en SalesOS. En lugar de consultar la API periódicamente, SalesOS envía los datos directamente a tu endpoint.
¿Cómo funcionan?
Registra tu endpoint
Configura la URL que recibirá las notificaciones.
Selecciona los eventos
Elige qué eventos deseas recibir.
Recibe las notificaciones
SalesOS envía una solicitud POST a tu endpoint cada vez que ocurre un evento suscrito.
Confirma la recepción
Tu endpoint debe responder con un código 200 para confirmar que recibió la notificación.
Eventos disponibles Leads
Oportunidades
Usuarios
Gamificación
Evento Descripción lead.createdNuevo lead creado lead.updatedLead actualizado lead.deletedLead eliminado lead.stage_changedLead cambió de etapa lead.assignedLead asignado a un vendedor
Evento Descripción opportunity.createdNueva oportunidad creada opportunity.updatedOportunidad actualizada opportunity.stage_changedOportunidad cambió de etapa opportunity.wonOportunidad cerrada como ganada opportunity.lostOportunidad cerrada como perdida
Evento Descripción user.createdNuevo usuario creado user.updatedUsuario actualizado user.deactivatedUsuario desactivado
Evento Descripción badge.earnedUsuario ganó un badge challenge.completedDesafío completado ranking.updatedRanking actualizado
Registro de un webhook { "url" : "https://tu-servidor.com/webhook/salesos" , "events" : [ "lead.created" , "opportunity.won" ], "secret" : "tu_secreto_de_verificación" , "active" : true }
Cada notificación de webhook tiene el siguiente formato:
{ "id" : "evt_abc123" , "event" : "lead.created" , "timestamp" : "2026-03-15T10:30:00Z" , "data" : { "id" : "lead_xyz789" , "name" : "Juan Pérez" , "email" : "juan@empresa.com" , "stage" : "prospecting" } }
Verificación de firma Cada solicitud incluye un header X-SalesOS-Signature con una firma HMAC-SHA256 del payload. Verifica la firma para asegurar que la solicitud proviene de SalesOS:
import hmac import hashlib def verify_signature ( payload , signature , secret ): expected = hmac.new( secret.encode(), payload.encode(), hashlib.sha256 ).hexdigest() return hmac.compare_digest(expected, signature)
Reintentos Si tu endpoint no responde con un código 200, SalesOS reintentará la entrega:
Intento Espera 1 Inmediato 2 1 minuto 3 5 minutos 4 30 minutos 5 2 horas
Después de 5 intentos fallidos, el webhook se desactivará automáticamente. Revisa tus logs y reactívalo manualmente.
Procesa los webhooks de forma asíncrona. Responde con 200 inmediatamente y procesa los datos en segundo plano para evitar timeouts.
Próximos pasos
Integración n8n Usa webhooks con SalesOS Connect.
Integraciones personalizadas Construye integraciones a medida.
