Webhook

I webhook permettono alla tua applicazione di ricevere notifiche di eventi in tempo reale da PDFSimple. Invece di interrogare periodicamente l'API per lo stato dell'operazione, registra un endpoint e PDFSimple invierà una richiesta POST con un payload firmato quando si verifica un evento.

Configurare un webhook

1. Vai su Dashboard → Webhook e fai clic su Aggiungi endpoint.
2. Inserisci l'URL del tuo endpoint HTTPS (es. https://tuaapp.com/webhooks/pdfsimple).
3. Seleziona gli eventi che vuoi ricevere (es. job.completed, job.failed).
4. Fai clic su Crea. Viene mostrata una chiave segreta univoca per il webhook: copiala subito, viene mostrata una sola volta.
5. Conserva la chiave segreta in modo sicuro nelle variabili d'ambiente della tua applicazione.

Eventi webhook

• job.completed — un'operazione di elaborazione PDF è terminata con successo. Il payload include l'ID dell'operazione, l'URL del file di output e i metadati.
• job.failed — un'operazione ha riscontrato un errore. Il payload include il messaggio di errore.

Verificare le firme dei webhook

Ogni richiesta webhook include un'intestazione X-PDFSimple-Signature contenente una firma HMAC-SHA256 del corpo grezzo della richiesta, calcolata usando la tua chiave segreta webhook. Verifica sempre questa firma prima di elaborare il payload.

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)
  );
}

Tentativi e garanzie di consegna

Se il tuo endpoint non restituisce una risposta 2xx entro 30 secondi, PDFSimple riproverà la consegna con backoff esponenziale, fino a 5 tentativi in 30 giorni. Gli eventi webhook vengono conservati per 30 giorni.