Webhooks

Los webhooks permiten que tu aplicación reciba notificaciones de eventos en tiempo real desde PDFSimple. En lugar de consultar la API repetidamente para conocer el estado de un trabajo, registra un endpoint y PDFSimple le enviará una solicitud POST con una carga útil firmada cuando ocurra un evento.

Configurar un webhook

1. Ve a Panel → Webhooks y haz clic en Añadir endpoint.
2. Introduce la URL de tu endpoint HTTPS (por ejemplo, https://tuaplicacion.com/webhooks/pdfsimple).
3. Selecciona los eventos que quieres recibir (por ejemplo, job.completed, job.failed).
4. Haz clic en Crear. Se mostrará un secreto de webhook único; cópialo de inmediato, solo se muestra una vez.
5. Guarda el secreto de forma segura en las variables de entorno de tu aplicación.

Eventos de webhook

• job.completed: un trabajo de procesamiento de PDF finalizó correctamente. La carga útil incluye el ID del trabajo, la URL del archivo de salida y los metadatos.
• job.failed: un trabajo encontró un error. La carga útil incluye el mensaje de error.

Verificar las firmas de webhook

Cada solicitud de webhook incluye un encabezado X-PDFSimple-Signature que contiene una firma HMAC-SHA256 del cuerpo de la solicitud sin procesar, calculada con tu secreto de webhook. Verifica siempre esta firma antes de procesar la carga útil.

const crypto = require('crypto');

function verifySignature(rawBody, secret, signature) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Reintentos y garantías de entrega

Si tu endpoint no devuelve una respuesta 2xx en un plazo de 30 segundos, PDFSimple reintentará la entrega con retroceso exponencial, hasta 5 intentos durante 30 días. Los eventos de webhook se conservan durante 30 días.