Webhooks: eventos a sistemas externos
Los webhooks envían automáticamente mensajes a una URL externa cuando ocurren eventos específicos en Tesoro: nuevo lead, cambio de estado de una operación a “Ganada”, propiedad “Vendida”. Se utilizan para integraciones con Zapier, Make, sistemas propios.
¿Cuándo se utiliza esto?
Sección titulada «¿Cuándo se utiliza esto?»- Nuevo lead a un canal de Slack mediante Zapier
- Evento de operación ganada a su sistema de contabilidad
- Hacer que una herramienta de análisis externa reciba datos en tiempo real
¿Qué es un webhook?
Sección titulada «¿Qué es un webhook?»Con cada evento seleccionado, Tesoro envía una solicitud HTTP POST a su URL con un payload JSON. Su sistema recibe, procesa y responde (200 OK).
Crear un webhook
Sección titulada «Crear un webhook»- Settings → Webhooks → Add webhook.
- Complete:
- Name: nombre reconocible
- URL: endpoint que recibe el payload (se recomienda HTTPS)
- Events: seleccione qué eventos activan el webhook
- Secret (opcional), para validación de solicitudes
- Save → el webhook se activa.
Eventos disponibles
Sección titulada «Eventos disponibles»| Categoría | Events |
|---|---|
| Lead | created, updated, status_changed, converted, deleted |
| Contact | created, updated, deleted, portal_user_created |
| Deal | created, status_changed, won, lost, deleted |
| Property | created, status_changed, sold, rented, deleted |
| Meeting | created, status_changed, completed |
| Activity | task_created, task_completed, note_created |
Seleccione al menos 1, puede seleccionar varios.
Formato del payload
Sección titulada «Formato del payload»El cuerpo JSON contiene:
event: tipo (ej.lead.created)timestamp: cuándo ocurriódata: registro completo con todos los camposprevious_data(en caso de cambios), estado anteriorcompany_id: para integraciones multi-tenant
Autenticación y seguridad
Sección titulada «Autenticación y seguridad»Validación con secret (recomendada): Tesoro firma cada webhook con HMAC. Su endpoint calcula el mismo HMAC y lo valida.
Sin secret: cualquier POST puede provenir de cualquier origen. No se recomienda para sistemas en producción.
Comportamiento de reintento
Sección titulada «Comportamiento de reintento»¿El webhook falla (sin respuesta 200 dentro de X segundos, o timeout de red)? Tesoro reintenta:
- 1 minuto después
- 5 minutos después
- 30 minutos después
- 2 horas después
- Luego se marca como Failed, sin más intentos
Los webhooks fallidos son visibles en el panel. Es posible reintentar manualmente.
Registros del webhook
Sección titulada «Registros del webhook»Por cada webhook puede ver los últimos intentos:
- Marca de tiempo
- Tipo de evento
- Estado de la respuesta
- Número de reintentos
- Cuerpo (entrada/salida)
Ayuda a depurar.
Errores comunes
Sección titulada «Errores comunes»No se reciben eventos
Sección titulada «No se reciben eventos»Verifique:
- ¿La URL es accesible desde internet?
- ¿El certificado HTTPS es válido?
- ¿El endpoint envía una respuesta 200 dentro de 5 segundos?
- ¿Los eventos están realmente seleccionados en la configuración del webhook?
Eventos duplicados
Sección titulada «Eventos duplicados»Comportamiento de reintento del webhook: debido a problemas de sincronización, a veces recibe un reintento de una entrega ya exitosa. Haga que su endpoint sea idempotente: si recibe el mismo ID de evento dos veces, procese solo una vez.