Skip to main content

Webhooks (Salientes)

Los webhooks permiten que SalesOS llame a tu sistema cuando algo ocurre (un lead es ofertado, un ranking se publica, un mensaje se despacha). Nos das una URL HTTPS y un secreto; hacemos POST de un payload JSON firmado cada vez que dispara un evento suscrito.
Esta página cubre webhooks salientes (SalesOS → tu endpoint). Para enviar datos hacia SalesOS, consulta Actividades y API Keys.

Configurar un webhook en el Dashboard

Ve a Integraciones → Webhooks → Nuevo Webhook y completa el formulario.
1

Básico

  • Nombre (obligatorio) — ej.: Notificar CRM.
  • Clave — un identificador estable (ej.: notify_crm).
  • Descripción — opcional.
2

Eventos (disparadores)

Elige una Categoría y selecciona los eventos que disparan este webhook — esta es tu suscripción (ver el catálogo). Déjalo vacío para un webhook que solo disparas manualmente (botón Probar) o desde un workflow.
3

Destino

  • MétodoPOST (por defecto), PUT o PATCH.
  • Timeout (segundos) — cuánto esperamos tu 2xx (por defecto 30).
  • URL (obligatorio) — tu endpoint. Debe ser https:// y público (hosts internos/loopback están bloqueados).
  • Autenticación — elige HMAC para firmar cada entrega y, en Configuración de Autenticación (JSON), indica tu secreto:
    (Otros esquemas disponibles: Bearer, API Key, Basic, OAuth2.)
4

Avanzado

  • Headers Personalizados (JSON) — headers extra enviados en cada entrega.
  • Plantilla del Payload (JSON con variables {{ }}) — modela el data del envelope a partir del contexto del evento, ej.: { "id": "{{event.id}}", "type": "{{event.type}}", "to": "{{event.to}}" }.
Los valores de la plantilla se interpolan en JSON. Usa campos planos y escalares. Inyectar un objeto anidado vía "{{event.data}}" puede no renderizar limpio hoy — revisa siempre el Preview / envía una Prueba antes.
5

Preview, probar y guardar

El formulario muestra un Preview en vivo (headers + cuerpo). Haz clic en Guardar webhook y usa Probar Webhook para enviar una entrega de ejemplo y confirmar que tu endpoint recibe — y verifica — el payload.

El envelope

En la ruta de evento, cada entrega es un único objeto JSON:

Headers

Verificar la firma

Verifica siempre la firma antes de confiar en una entrega. Sin ella, cualquiera que descubra tu URL podría falsificar eventos.
En la ruta de evento, la firma cubre {id}.{timestamp}.{rawBody} (estilo Standard Webhooks), por lo que autentica el payload y el timestamp (anti-replay). Recalcula el HMAC con tu secreto, compara en tiempo constante y rechaza si el timestamp está a más de 300s.
Entregas de prueba (el botón “Probar Webhook”) y los disparadores legados de workflow usan hoy un esquema más simple: el cuerpo es la plantilla renderizada cruda (no el envelope) y el header de firma es X-Signature: <prefijo><hmac(cuerpo)>sin el prefijo id.timestamp., por lo que no tiene anti-replay. Prefiere la ruta de evento de arriba en producción.

Catálogo de eventos

Check-in: los tres momentos en que la fila cambia

La elegibilidad cambia en exactamente tres momentos, y cada uno tiene su evento. Si usted enruta leads según quién está en turno, suscríbase a los tres — tomar solo el primero deja a las personas habilitadas para siempre.
Un check-in que no vuelve elegible a la persona nunca llega hasta usted. Entregarlo indicaría habilitar en la fila a quien no puede recibir leads.
La expiración por inactividad — la app sin dar señal por cuatro horas — es red de seguridad, no regla, y a propósito no llega hasta usted. Sigue avisando al propio colaborador.
La expiración la evalúa una rutina que corre cada 15 minutos, así que checkin.shift_closed puede llegar hasta 15 minutos después del cierre del turno. Si su lado exige un corte exacto, use el fin de turno de la API de Check-in en vez de esperar el evento.
Cada evento de check-in llega con el bloque user — la identidad de quien entró o salió de la fila, resuelta de nuestro lado para que usted reconozca a la persona sin acuerdo previo de integración. Ejemplo de data para checkin.confirmed:
user.cpf puede venir null — no todo colaborador tiene documento registrado; caiga a user.email. Los campos que no existen en el momento del evento (p. ej. shift en una salida registrada) llegan como null, nunca desaparecen del schema.
Ejemplo de data para ranking.weekly.published:
Los destinatarios se identifican por email — nombres e ids no se envían; enriquece de tu lado si lo necesitas.

Confiabilidad

Responde rápido. Devuelve un estado 2xx rápidamente (antes de procesamiento pesado) para confirmar la recepción. Idempotencia. El mismo evento puede entregarse más de una vez (reintentos). Deduplica por X-SalesOS-Event-Id — se mantiene igual entre reintentos.
Las entregas fallidas aparecen en el panel Entregas (Dashboard → Integraciones → Webhooks), donde puedes inspeccionar estado, intentos y el último error, y reenviar desde la cola de dead-letter.