Webhooks y Notificaciones

Configura notificaciones automáticas en tiempo real sobre tus transcripciones. Aprende a configurar webhooks, implementar seguridad e integrarlos con tus sistemas.

¿Por qué usar Webhooks?

Eventos Disponibles

| Evento | Descripción | Carga útil | |---|---|---| | transcription.started | Transcripción inició su procesamiento | ID de subida, motor, marca de tiempo | | transcription.progress | Progreso actualizado | ID de subida, porcentaje, estimación | | transcription.completed | Transcripción completada exitosamente | ID de subida, texto, duración, créditos | | transcription.failed | Transcripción falló | ID de subida, error, tipo de error | | transcription.retry | Intento de reintento iniciado | ID de subida, intento, motor | | upload.completed | Carga de archivo completada | ID de subida, tamaño, formato | | credits.low | Créditos por debajo del umbral configurado | Saldo actual, umbral |

Configuración Paso a Paso

Ejemplos de Implementación

Node.js (Express)

const express = require('express');
const crypto = require('crypto');

const app = express();
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

app.post('/webhook/voxscriber', express.raw({ type: 'application/json' }), (req, res) => {
  // Verificar firma
  const signature = req.headers['x-webhook-signature'];
  const hash = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  if (signature !== hash) {
    return res.status(401).send('Firma inválida');
  }

  const event = JSON.parse(req.body);

  switch (event.type) {
    case 'transcription.completed':
      console.log('Transcripción completada:', event.data.uploadId);
      // Procesar resultado
      break;
    case 'transcription.failed':
      console.log('Transcripción fallida:', event.data.error);
      // Manejar error
      break;
  }

  res.status(200).json({ received: true });
});

Python (Flask)

import hmac
import hashlib
from flask import Flask, request, jsonify

app = Flask(__name__)
WEBHOOK_SECRET = os.environ['WEBHOOK_SECRET']

@app.route('/webhook/voxscriber', methods=['POST'])
def handle_webhook():
    # Verificar firma
    signature = request.headers.get('X-Webhook-Signature')
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        request.data,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        return jsonify({'error': 'Firma inválida'}), 401

    event = request.json

    if event['type'] == 'transcription.completed':
        process_transcription(event['data'])
    elif event['type'] == 'transcription.failed':
        handle_failure(event['data'])

    return jsonify({'received': True}), 200

Seguridad y Buenas Prácticas

Buenas prácticas de seguridad:

• Valida la firma HMAC-SHA256 de cada solicitud
• Usa HTTPS en el endpoint receptor
• Implementa idempotencia (mismo evento procesado solo una vez)
• Rota el secreto del webhook periódicamente
• Registra todos los eventos recibidos para auditoría

Buenas prácticas de implementación:

• Responde con 200 OK rápidamente (en menos de 5 segundos)
• Procesa eventos de forma asíncrona
• Implementa una cola de procesamiento para alta carga
• Supervisa los fallos de entrega en el panel de control

Mecanismo de Reintento

Cuando tu endpoint no responde correctamente (2xx), VoxScriber reintenta la entrega:

| Intento | Intervalo | Descripción | |---|---|---| | 1 | Inmediato | Primer intento | | 2 | 1 minuto | Después del fallo inicial | | 3 | 5 minutos | Segundo reintento | | 4 | 30 minutos | Tercer reintento | | 5 | 2 horas | Intento final |

Después de 5 fallos consecutivos, el webhook se desactiva automáticamente y recibes una notificación por correo electrónico.

Solución de Problemas

El Webhook no se recibe

Causas posibles: URL incorrecta, firewall bloqueando, certificado SSL inválido.

Soluciones: Verifica la URL en el panel de control, permite la IP de VoxScriber en tu firewall, valida tu certificado SSL.

Firma inválida

Causas posibles: Secreto incorrecto, codificación del cuerpo diferente, middleware modificando el cuerpo.

Soluciones: Confirma el secreto en el panel de control, usa el cuerpo sin procesar para la verificación, desactiva el middleware de análisis antes de la verificación.

Eventos duplicados

Causas posibles: Reintento tras tiempo de espera, respuesta lenta del servidor.

Soluciones: Implementa idempotencia usando el event.id, responde con 200 OK rápidamente, procesa de forma asíncrona.

Continuar aprendiendo

• Integración de API - Documentación completa de la API
• Automatización de flujos de trabajo - Automatiza procesos con webhooks
• Procesamiento por lotes - Transcribe múltiples archivos