Webhooks

Webhooks allow your application to receive real-time event notifications from PDFSimple. Instead of polling the API for job status, register an endpoint and PDFSimple will POST a signed payload to it when an event occurs.

Setting up a webhook

1. Go to Dashboard → Webhooks and click Add endpoint.
2. Enter your HTTPS endpoint URL (e.g., https://yourapp.com/webhooks/pdfsimple).
3. Select the events you want to receive (e.g., job.completed, job.failed).
4. Click Create. A unique webhook secret is displayed — copy it immediately, it is shown only once.
5. Store the secret securely in your application's environment variables.

Webhook events

• job.completed — a PDF processing job finished successfully. The payload includes the job ID, output file URL, and metadata.
• job.failed — a job encountered an error. The payload includes the error message.

Verifying webhook signatures

Every webhook request includes an X-PDFSimple-Signature header containing an HMAC-SHA256 signature of the raw request body, computed using your webhook secret. Always verify this signature before processing the 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)
  );
}

Retries and delivery guarantees

If your endpoint does not return a 2xx response within 30 seconds, PDFSimple will retry the delivery with exponential back-off, up to 5 attempts over 30 days. Webhook events are retained for 30 days.