Webhooks - Introducción

Los webhooks de TSALVA te permiten recibir notificaciones en tiempo real sobre cambios de estado en tus servicios, manteniéndote siempre informado del progreso sin necesidad de hacer consultas constantes.

¿Qué son los Webhooks?

Un webhook es una notificación HTTP automática que TSALVA envía a tu servidor cuando ocurre un evento específico en un servicio. Es como una "llamada telefónica" que el sistema te hace para informarte de cambios importantes.

🔄 Comparación: Webhooks vs Polling

Aspecto	Webhooks	Polling
Tiempo real	✅ Inmediato	❌ Retraso según frecuencia
Eficiencia	✅ Solo cuando hay cambios	❌ Consultas constantes
Recursos	✅ Bajo consumo	❌ Alto consumo
Complejidad	⚠️ Configuración inicial	✅ Simple de implementar

Eventos Disponibles

🎯 Aceptación de Oferta

Se notifica cuando una central acepta tu oferta de servicio:

{
  "tipo": "aceptacion",
  "oferta_id": "123e4567-e89b-12d3-a456-426614174000",
  "prestador": "Central Norte SAS",
  "tecnico": {
    "id": "TEC001",
    "telefono": "+57 300-123-4567"
  },
  "eta": "25 minutos"
}

🔄 Cambios de Estado

Se notifica en cada cambio de estado del servicio:

graph LR
    A[Aceptado] --> B[En Camino]
    B --> C[En Sitio]
    C --> D[En Proceso]
    D --> E[Completado]
    
    style A fill:#e3f2fd
    style B fill:#fff3e0
    style C fill:#f3e5f5
    style D fill:#e8f5e8
    style E fill:#e0f2f1

Estados típicos:

• ACEPTADO - Central acepta el servicio
• EN_CAMINO - Técnico se dirige al sitio
• EN_SITIO - Técnico llegó al lugar
• EN_PROCESO - Servicio en ejecución
• COMPLETADO - Servicio finalizado
• INCOMPLETO - Servicio no completado
• CANCELADO - Servicio cancelado

Flujo de Webhooks

sequenceDiagram
    participant Tu_App as Tu Aplicación
    participant TSALVA as TSALVA API
    participant Central
    participant Tu_Hook as Tu Webhook

    Tu_App->>TSALVA: 1. Crear oferta
    TSALVA-->>Tu_App: Oferta creada
    
    TSALVA->>Central: 2. Distribuir oferta
    Central->>TSALVA: Aceptar oferta
    
    TSALVA->>Tu_Hook: 3. Webhook aceptación
    Tu_Hook-->>TSALVA: 200 Correcto
    
    Central->>TSALVA: 4. Técnico en camino
    TSALVA->>Tu_Hook: Webhook cambio estado
    Tu_Hook-->>TSALVA: 200 Correcto
    
    Central->>TSALVA: 5. Servicio completado
    TSALVA->>Tu_Hook: Webhook completado
    Tu_Hook-->>TSALVA: 200 Correcto

Beneficios de los Webhooks

⚡ Tiempo Real

• Notificaciones instantáneas
• No esperas a consultar manualmente
• Usuario final siempre informado

🎯 Precisión

• Solo recibes eventos relevantes
• No hay información duplicada
• Datos específicos de cada estado

📱 Experiencia de Usuario

• Actualizar UI en tiempo real
• Enviar notificaciones push
• Mostrar progreso actualizado

💰 Eficiencia

• Reduce llamadas a la API
• Menor uso de ancho de banda
• Ahorro en costos de infraestructura

Casos de Uso Comunes

📱 Aplicación Móvil

// Al recibir webhook de "EN_CAMINO"
app.put('/webhook/tsalva', (req, res) => {
  const { idServicio, codigoEstado, detalleEstado } = req.body;
  
  if (codigoEstado === 'EN_CAMINO') {
    // Enviar notificación push al usuario
    pushNotification.send(usuario_id, {
      title: '🚗 Técnico en camino',
      body: `Tu técnico llegará en ${detalleEstado.eta} minutos`,
      data: { servicio_id: idServicio }
    });
    
    // Actualizar estado en base de datos
    database.updateServiceStatus(idServicio, 'EN_CAMINO');
  }
  
  res.json({ received: true });
});

🌐 Dashboard Web

// WebSocket para actualizar UI en tiempo real
app.put('/webhook/tsalva', (req, res) => {
  const webhookData = req.body;
  
  // Broadcast a usuarios conectados
  io.emit('service_update', {
    servicio: webhookData.idServicio,
    estado: webhookData.codigoEstado,
    detalle: webhookData.detalleEstado
  });
  
  res.json({ received: true });
});

// En el frontend
socket.on('service_update', (data) => {
  updateServiceCard(data.servicio, data.estado);
  showNotification(`Servicio ${data.servicio}: ${data.estado}`);
});

📧 Sistema de Notificaciones

# Enviar emails automáticos según el estado
@app.route('/webhook/tsalva', methods=['PUT'])
def webhook_tsalva():
    data = request.get_json()
    codigo_estado = data['codigoEstado']
    detalle = data['detalleEstado']
    
    if codigo_estado == 'COMPLETADO':
        send_completion_email(
            cliente_email=get_client_email(data['idServicio']),
            tarifa=detalle.get('tarifaServicio'),
            duracion=detalle.get('tiempo')
        )
    elif codigo_estado == 'INCOMPLETO':
        send_issue_notification(
            admin_email='admin@empresa.com',
            servicio=data['idServicio'],
            razon=detalle.get('razonIncompleto')
        )
    
    return jsonify({'received': True})

Configuración Básica

1. Crear Endpoint

Tu servidor debe tener un endpoint público que reciba peticiones PUT:

// Express.js
app.put('/webhook/tsalva', (req, res) => {
  // Validar API Key
  if (req.headers['x-apikey'] !== process.env.TSALVA_API_KEY) {
    return res.status(401).json({ error: 'Invalid API Key' });
  }
  
  // Procesar webhook
  const webhookData = req.body;
  processWebhook(webhookData);
  
  // Responder inmediatamente
  res.status(200).json({ received: true });
});

2. Configurar con TSALVA

Proporciona al equipo de TSALVA:

URL: https://tu-dominio.com/webhook/tsalva
API_KEY: tu_clave_secreta_unica
Method: PUT
Content-Type: application/json

3. Validar Funcionamiento

# Test manual del webhook
curl -X PUT "https://tu-dominio.com/webhook/tsalva" \
  -H "x-apikey: tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "idServicio": "TEST_123",
    "codigoEstado": "TEST",
    "detalleEstado": { "test": true }
  }'

Mejores Prácticas

🔒 Seguridad

• Validar API Key: Siempre verificar la autenticidad
• HTTPS: Usar conexiones seguras
• Firewall: Restringir acceso solo desde IPs de TSALVA

⚡ Rendimiento

• Respuesta rápida: Responder con 200 Correcto inmediatamente
• Procesamiento asíncrono: Usar colas para tareas largas
• Idempotencia: Manejar webhooks duplicados

🔄 Confiabilidad

• Logs detallados: Registrar todos los webhooks recibidos
• Manejo de errores: Códigos de estado apropiados
• Reintentos: TSALVA reintentará si no respondes con 200

Webhooks Disponibles

Webhook	Descripción	Documentación
Cambio de Estado	Notificaciones de cambios en servicios	Ver detalles →

Próximos Pasos

1. Configurar tu webhook - Guía paso a paso
2. Implementar cambio de estado - Webhook principal
3. Ver ejemplos de código - Implementaciones prácticas

---

¿Necesitas ayuda?

El equipo de TSALVA puede ayudarte con la configuración inicial y pruebas de conectividad. Contacta a soporte@robpixels.com.

Importante

Tu endpoint debe estar accesible públicamente y responder en menos de 30 segundos. Para procesamientos largos, usa colas asíncronas.