Webhooks

¿Qué son los Webhooks?

Los Webhooks permiten que tu aplicación reciba notificaciones en tiempo real sobre eventos que ocurren en Quote3D. En lugar de consultar nuestra API para obtener actualizaciones (por ejemplo, verificar si una cotización ha finalizado), Quote3D enviará una solicitud HTTP POST a una URL que especifiques tan pronto como ocurra un evento.

Esto es mucho más eficiente y te permite activar flujos de trabajo automatizados en tu propio sistema, como actualizar el estado de un pedido, notificar a un cliente o iniciar un trabajo de producción.

Eventos Disponibles

• quote.completed: Se activa cuando se finaliza correctamente el cálculo de un presupuesto de impresión 3D.
• quote.failed: Se activa si falla el cálculo de un presupuesto por cualquier motivo.
• file.uploaded: Se activa cuando se carga correctamente un nuevo archivo de modelo a tu cuenta.
• file.deleted: Se activa cuando se elimina un archivo de modelo de tu almacenamiento.
• job.status_changed: Se activa durante varias etapas de un trabajo de procesamiento asíncrono.
• widget.added_to_cart: Se activa cuando un cliente añade un modelo a su carrito utilizando tu widget incrustable.

Ejemplo de carga útil

Todas las solicitudes webhook se envían como JSON. Aquí hay un ejemplo de una carga útil del evento quote.completed:

{
  "event": "quote.completed",
  "timestamp": "2026-03-10T14:30:00.000Z",
  "data": {
    "jobId": "job_01HXYZ123456789",
    "quoteId": "job_01HXYZ123456789",
    "status": "completed",
    "fileName": "gearbox-housing.stl",
    "fileId": "fl_987654321",
    "processingTimeMs": 22134,
    "result": {
      "quote_id": "job_01HXYZ123456789",
      "total_price": 25.5,
      "currency": "USD",
      "estimated_time": "2h 15m",
      "estimated_time_seconds": 8100,
      "filament_weight": 42.8,
      "printInfo": {
        "technology": "FDM",
        "material": "PLA",
        "color": "Black"
      }
    },
    "error": null
  }
}

Seguridad y Verificación

Para asegurar que las solicitudes webhook son genuinamente de Quote3D y no han sido manipuladas, incluimos una firma HMAC-SHA256 en la cabecera X-Webhook-Signature.

Cuando cree un webhook en el panel de control, se le mostrará una Clave Secreta única. Debe usar esta clave para verificar la firma de cada solicitud entrante.

Pasos de Verificación:

1. Lea el cuerpo de la solicitud sin procesar como una cadena.
2. Recupere la firma de la cabecera X-Webhook-Signature y el nombre del evento de X-Webhook-Event.
3. Calcule el hash HMAC-SHA256 del cuerpo sin procesar utilizando su Clave Secreta de Webhook.
4. Prefija tu digest calculado con sha256= y compáralo con la firma. Si coinciden, la solicitud es auténtica.

const crypto = require('crypto');

// Secret Key from your Quote3D Dashboard
const SECRET = 'your_webhook_secret_here';

function verifySignature(req) {
  const signature = req.headers['x-webhook-signature'];
  const event = req.headers['x-webhook-event'];
  const body = req.rawBody; // Keep the exact raw JSON string

  const hmac = crypto.createHmac('sha256', SECRET);
  const digest = 'sha256=' + hmac.update(body).digest('hex');

  if (typeof signature !== 'string' || typeof event !== 'string') {
    return false;
  }

  const received = Buffer.from(signature, 'utf8');
  const expected = Buffer.from(digest, 'utf8');

  return received.length === expected.length &&
    crypto.timingSafeEqual(received, expected);
}

Administración de Webhooks

Puedes administrar tus webhooks directamente desde el Panel de Control:

1. Ve a la página de Webhooks en tu panel de control.
2. Haz clic en Nuevo Webhook para agregar un nuevo punto final.
3. Ingresa tu URL del Punto Final (debe ser HTTPS) y selecciona los Eventos que deseas escuchar.
4. Copia tu Clave Secreta inmediatamente y guárdala de forma segura. ¡No podrás verla de nuevo!
5. Proporciona un enlace de Token de API opcional si deseas que el webhook solo se active para las acciones realizadas con ese token específico.

Reintentando Entregas Fallidas

Si un destino de webhook estuvo temporalmente no disponible o devolvió un error, puede inspeccionar la entrega en el panel de control y activar un reenvío para ese registro de entrega específico.

Mejores Prácticas

• Devuelve un estado 200 OK inmediatamente para acusar recibo del webhook.
• Realice el procesamiento intensivo de forma asíncrona (por ejemplo, utilizando una cola de tareas en segundo plano) para evitar tiempos de espera.
• Siempre verifique la firma para proteger su punto final de solicitudes no autorizadas.
• Idempotencia: Asegúrese de que su sistema pueda manejar el mismo webhook varias veces sin problemas, ya que podemos reintentar las entregas en caso de errores transitorios.