Async PDF Generation with Webhooks

Updated October 30, 2026 · 7 min read

Long reports and bulk invoices should not block an HTTP request. Use webhooks to queue the job and receive the result when it is ready.

1. Sync vs async

• Synchronous: small documents where the caller needs the file immediately.
• Asynchronous: large reports, bulk jobs, retries, or long rendering times.

2. Queue a job

Set webhook: true. The API returns 202 with a PDF ID and pending status. The result is posted to your project webhook.

const job = await client.generate({
  templateId: 'YOUR_TEMPLATE_ID',
  data,
  webhook: true
});

console.log(job.id, job.status); // pending

3. What the webhook receives

The payload includes id, status, success, testResults, and a downloadUrl. It does not include the PDF binary. The download URL expires after 15 minutes. Experimental PDF/UA-2 jobs also include compliance, experimental, and warnings; see PDF/UA-2 generation.

const { id, status, success, testResults, downloadUrl } = req.body;

Failed deliveries include error and a short-lived rawPayloadUrl so your backend can repair and resubmit the job.

4. Verify the signature

Every webhook includes x-webhook-signature. Verify the HMAC-SHA256 signature before trusting the payload.

Verify PDF webhooks

5. Retries and DLQ

Non-2xx responses are retried three times with backoff. After the final attempt, the payload moves to your dead letter queue and is retained for three days. Respond with a 2xx quickly and do slow work in your own queue.

Webhook retries and recovery

6. Idempotency and status

Use the PDF ID as the idempotency key. Store the status and download URL; do not regenerate the PDF when a duplicate delivery arrives. If the job failed, decide whether to retry the original payload or repair it.

7. Layout checks in async jobs

If the job uses a testCase, inspect testResults in the webhook payload before delivering the file. Keep the result under 8 KB of JSON.

Automated PDF layout testing

8. Production checklist

• Return 2xx before doing slow work.
• Verify the webhook signature.
• Download and store the file before the URL expires.
• Handle duplicate deliveries and retries idempotently.
• Monitor the DLQ.
• Respect the request, PDF, ZIP, and testResults limits.