Webhooks para eventos de presupuestos y trabajos

¿Qué son los Webhooks?

Los Webhooks permiten que su 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 especifique tan pronto como ocurra un evento.

Esto es mucho más eficiente y le permite activar flujos de trabajo automatizados en su 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 su cuenta.
• file.deleted: Se activa cuando se elimina un archivo de modelo de su almacenamiento.
• job.status_changed: Se activa en cada transición de estado de un trabajo asíncrono (en cola, procesando, completado, fallido). Un solo presupuesto genera varios de estos.
• widget.added_to_cart: Se activa cuando un cliente añade un modelo a su carrito utilizando su widget incrustable.

Requisitos del endpoint

La URL de su endpoint se valida al guardarla y nuevamente antes de cada intento de entrega. Las URL que no cumplan con estas reglas serán rechazadas con una respuesta 400.

• Debe usar http o https. Otros esquemas serán rechazados.
• No debe incluir credenciales. https://user:[email protected] será rechazada.
• No debe resolverse a una dirección privada o reservada: localhost, loopback, link-local (incluyendo metadatos de instancias en la nube), rangos privados, CGNAT, multicast y espacio reservado.
• El nombre de host se resuelve mediante DNS en cada intento, por lo que también se rechazará un nombre de host público que apunte a un espacio privado.
• No se siguen las redirecciones. Devuelva su respuesta directamente desde la URL que registró.

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. Prefije su digest calculado con sha256= y compárelo 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

Puede administrar sus webhooks directamente desde el Panel de Control:

1. Vaya a la página de Webhooks en su panel de control.
2. Haga clic en Nuevo Webhook para agregar un nuevo punto final.
3. Ingrese su URL de endpoint y seleccione los eventos que desea escuchar. Se recomienda encarecidamente el uso de HTTPS; consulte los Requisitos del endpoint arriba.
4. Copie su Clave Secreta inmediatamente y guárdela de forma segura. ¡No podrá verla de nuevo!
5. Vincule opcionalmente un token de API. Si lo deja vacío, el webhook se activará para cada solicitud en su cuenta; si vincula un token, se activará solo para las solicitudes realizadas con ese token.

Reintentando Entregas Fallidas

Reintentos automáticos

Una entrega fallida se reintenta automáticamente antes de que sea necesario intervenir. Se realizan hasta 3 intentos de entrega; después de eso, la entrega se cierra como fallida y permanece visible en el panel de control.

• El primer intento ocurre tan pronto como se dispara el evento. Los intentos restantes son gestionados por un barrido en segundo plano, por lo que el intervalo práctico entre intentos lo determina dicho intervalo de barrido en lugar de un número fijo de segundos.
• Si nuestro proceso se interrumpe a mitad de un intento, la entrega se recupera y se reintenta en lugar de perderse.
• Cada entrega se reclama de forma atómica antes de enviarse, por lo que un reintento nunca resulta en que la misma entrega se envíe dos veces de forma simultánea.
• Un reintento envía exactamente el mismo cuerpo y la misma X-Webhook-Signature que el intento original, por lo que su lógica de verificación existente funcionará sin cambios.

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.