Webhooks

Recibe notificaciones en tiempo real cuando ocurren eventos.

Descripción General

Los webhooks te permiten:

• Obtener notificaciones instantáneas de eventos
• Automatizar flujos de trabajo
• Sincronizar con sistemas externos
• Construir integraciones reactivas

Requisito de Plan

El acceso a webhooks requiere un plan que incluya características de API.

Cómo Funcionan los Webhooks

1. Configuras una URL de endpoint
2. Seleccionas eventos a los que suscribirte
3. Cuando ocurren eventos, enviamos solicitudes HTTP POST
4. Tu servidor procesa el payload
5. Respondes con código de estado 2xx

Eventos Disponibles

Evento	Descripción
photo_request.created	Nueva solicitud de fotos creada
photo_request.first_viewed	Solicitud vista por primera vez
photo_submission.created	Fotos enviadas (Enlaces Permanentes)
photo_request.submitted	Solicitud única completada
photo_request.expired	Solicitud expiró sin envío
photo_submission.dropbox_synced	Foto sincronizada en Dropbox con enlace compartido

Crear un Webhook

Pasos

1. Ve a Webhooks en la barra lateral
2. Haz clic en Crear Webhook
3. Introduce un nombre descriptivo
4. Proporciona tu URL de endpoint
5. Selecciona eventos a suscribir
6. Activa Activo (predeterminado: activado)
7. Haz clic en Crear

Requisitos del Endpoint

Requisito	Valor
Protocolo	HTTPS requerido
Accesibilidad	Internet público
Respuesta	Código de estado 2xx
Timeout	30 segundos máximo

Redes Privadas

Las direcciones de redes privadas e internas (localhost, 10.x.x.x, 192.168.x.x) no están permitidas.

Payload del Webhook

Formato de Solicitud

POST /tu-endpoint HTTP/1.1
Host: tu-servidor.com
Content-Type: application/json
X-Webhook-Signature: sha256=abc123...
X-Webhook-ID: wh_123456
X-Webhook-Timestamp: 1609459200

Estructura del Payload

{
  "event": "photo_request.submitted",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "req_abc123",
    "type": "one_time",
    "instructions": "Envía fotos del vehículo",
    "photos": [
      {
        "id": "photo_xyz789",
        "url": "https://...",
        "slot_instructions": "Vista frontal",
        "metadata": {
          "gps_lat": 45.1234,
          "gps_lng": 12.5678,
          "captured_at": "2024-01-15T10:28:00Z"
        }
      }
    ],
    "submitted_at": "2024-01-15T10:30:00Z"
  }
}

Verificación de Firma

Por Qué Verificar

Verifica las firmas de webhook para asegurar:

• La solicitud vino de Visiono
• El payload no fue manipulado
• Prevenir ataques de repetición

Cabecera de Firma

X-Webhook-Signature: sha256=abc123def456...

Pasos de Verificación

// Ejemplo PHP
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'];
$secret = 'tu-secreto-webhook';

$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Firma inválida');
}

// Ejemplo Node.js
const crypto = require('crypto');

const payload = JSON.stringify(req.body);
const signature = req.headers['x-webhook-signature'];
const secret = process.env.WEBHOOK_SECRET;

const expected = 'sha256=' + crypto
  .createHmac('sha256', secret)
  .update(payload)
  .digest('hex');

if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
  return res.status(401).send('Firma inválida');
}

Gestionar Webhooks

Probar Webhook

Envía un evento de prueba:

1. Haz clic en Probar en el webhook
2. Confirma la acción
3. Verifica el estado de respuesta
4. Ve en logs si falló

Ver Logs

Consulta el historial de entregas:

1. Haz clic en Logs en el webhook
2. Ve las entregas recientes
3. Verifica estado y respuesta
4. Depura fallos

Detalles del Log

Cada log muestra:

• Tipo de evento
• Marca de tiempo
• Estado de respuesta
• Tiempo de respuesta
• Cuerpo de solicitud/respuesta (para depuración)

Regenerar Secreto

Obtén un nuevo secreto de firma:

1. Haz clic en Regenerar Secreto
2. Confirma la acción
3. Copia el nuevo secreto inmediatamente
4. Actualiza tu servidor

Actualiza el Servidor Primero

Después de regenerar, el secreto antiguo deja de funcionar. Actualiza tu código de verificación antes de regenerar.

Desactivar Webhook

Deja de recibir eventos temporalmente:

1. Haz clic en Desactivar
2. Confirma la acción
3. Los eventos ya no se envían
4. Reactiva cuando estés listo

Eliminar Webhook

Elimina permanentemente:

1. Haz clic en Eliminar
2. Confirma la acción
3. Todos los logs se eliminan

Política de Reintentos

Reintentos Automáticos

Las entregas fallidas se reintentan:

Intento	Retraso
1	Inmediato
2	1 minuto
3	5 minutos
4	30 minutos
5	2 horas

Criterios de Fallo

Una entrega falla si:

• Timeout de conexión (30s)
• Respuesta no 2xx
• Error de red
• Error SSL

Después de Máximos Reintentos

Si todos los reintentos fallan:

• El evento se marca como fallido
• Se registra para revisión
• No hay más intentos

Mejores Prácticas

Diseño del Endpoint

• Responde rápido (< 5 segundos)
• Procesa async si es necesario
• Devuelve 2xx inmediatamente
• Maneja idempotencia

Manejo de Errores

// Patrón recomendado
app.post('/webhook', async (req, res) => {
  // Verificar firma primero
  if (!verifySignature(req)) {
    return res.status(401).send('Inválido');
  }

  // Confirmar inmediatamente
  res.status(200).send('OK');

  // Procesar async
  processWebhookAsync(req.body);
});

Idempotencia

Los eventos pueden enviarse más de una vez. Maneja duplicados:

// Verificar si ya fue procesado
const eventId = req.headers['x-webhook-id'];
if (await isProcessed(eventId)) {
  return res.status(200).send('Ya procesado');
}

// Procesar y marcar como manejado
await processEvent(req.body);
await markProcessed(eventId);

Monitoreo

• Registra todos los webhooks entrantes
• Alerta en fallos
• Monitorea tiempos de respuesta
• Rastrea volúmenes de eventos

Solución de Problemas

No Se Reciben Eventos

1. Verifica que el webhook esté activo
2. Comprueba que la URL del endpoint sea correcta
3. Asegura que HTTPS funcione
4. Verifica que el servidor sea accesible
5. Comprueba eventos seleccionados

Discrepancia de Firma

1. Usa el secreto correcto
2. Compara el payload completo (no parseado)
3. Verifica problemas de codificación
4. Verifica algoritmo HMAC (SHA256)

Timeouts

1. Reduce el tiempo de procesamiento
2. Confirma inmediatamente
3. Procesa asincrónicamente
4. Verifica recursos del servidor

Ver Entregas Fallidas

1. Ve a logs del webhook
2. Filtra por estado (fallido)
3. Ve detalles de solicitud/respuesta
4. Corrige y vuelve a probar

Límites de Webhook

Por Plan

Plan	Máximo de Webhooks
Professional	5 webhooks
Enterprise	Ilimitados

Límites de Tasa

Límite	Valor
Eventos por minuto	100
Tamaño del payload	1 MB

Páginas Relacionadas

• Claves de API - Autenticación API
• Referencia de API - Documentación completa de API
• Integraciones - Integraciones preconstruidas