Async Workflow Details

Async conversion lets you queue PDF generation jobs and receive a signed webhook when each job finishes, so your application doesn't need to keep a request open while PDFBolt renders the document.

Async endpoint reference

This is a conceptual overview. For full parameters and webhook payloads, see the /v1/async endpoint reference.

The /v1/async endpoint is available on paid plans. Free plan users can use /v1/direct or /v1/sync.

The diagram below shows the async conversion flow:

When to Use Async Conversion

Use async conversion when your application doesn't need the PDF in the same HTTP response and can handle a signed webhook when the job finishes.

Use async when	Why it helps
You generate PDFs in batches or background jobs.	Your application can queue work and continue without holding client requests open.
Conversions may take longer because of large documents, heavy templates, or network-bound assets.	PDFBolt processes the job in the background and notifies your application when it finishes.
Your application can receive public HTTPS webhooks.	The webhook notifies your application when the conversion succeeds or fails permanently.
You want background generation with direct upload to your own S3-compatible bucket.	PDFBolt can upload the generated PDF to your customS3PresignedUrl and send a signed completion webhook.

For request/response flows where your application needs the PDF immediately, see /v1/direct or /v1/sync.

How the Asynchronous Flow Works

1. Submit Request

• Send a POST request to the /v1/async endpoint.
• Include the required webhook parameter – the URL where PDFBolt will deliver the result.
• For all parameters, see the /v1/async endpoint reference and conversion parameters.

Request Example:

{
  "url": "https://example.com",
  "webhook": "https://your-app.com/endpoint"
}

2. Immediate Acknowledgment

• The API responds immediately with a requestId, confirming the request was received.
• Your application can continue executing without waiting for the PDF generation to complete.

Response Example:

{
  "requestId": "7e075770-9c50-4018-a877-fc45c45b7850"
}

3. Background Processing

• PDFBolt processes async jobs in the background, and accepted jobs may run in parallel.
• New async requests are still subject to your plan's rate limits and concurrent request limits.

4. Direct S3 Upload (Optional)

• If you provide a customS3PresignedUrl, the generated PDF is uploaded directly to your S3‑compatible bucket.
• If no URL is provided, the PDF is temporarily stored in PDFBolt's bucket for 24 hours.

5. Webhook Notification

• Once the PDF is generated (or the conversion fails permanently), PDFBolt sends a single POST request to your webhook URL.
• Every webhook request includes an x-pdfbolt-signature header. See Webhook Signature Verification for details.

The webhook payload differs depending on whether you use default storage or a custom S3 bucket:

Default Storage – Success Example:

{
  "requestId": "a0f11722-907b-4308-be11-2c7f884f0ecc",
  "status": "SUCCESS",
  "errorCode": null,
  "errorMessage": null,
  "documentUrl": "https://s3.pdfbolt.com/pdfbolt_09366e47-2423-48c7-af8b-5eea118b49b3_2026-05-05T18-28-00Z.pdf",
  "expiresAt": "2026-05-06T18:28:00Z",
  "isAsync": true,
  "duration": 626,
  "documentSizeMb": 0.02,
  "isCustomS3Bucket": false
}

Custom S3 – Success Example:

{
  "requestId": "2bb49872-ff48-4c37-b104-dd5458c657cc",
  "status": "SUCCESS",
  "errorCode": null,
  "errorMessage": null,
  "documentUrl": null,
  "expiresAt": null,
  "isAsync": true,
  "duration": 626,
  "documentSizeMb": 0.02,
  "isCustomS3Bucket": true
}

When isCustomS3Bucket is true, both documentUrl and expiresAt are null – the PDF is stored in your bucket.

For the full list of webhook fields, see webhook request parameters.

Failure webhooks

If a conversion fails permanently, PDFBolt sends a webhook with status: "FAILURE" and includes errorCode and errorMessage. The documentUrl, expiresAt, and documentSizeMb fields are null. See the full failure example.

6. Document Retrieval

• Default storage – fetch the PDF from documentUrl before expiresAt (24 hours after generation).
• Custom S3 – the PDF is already in your bucket at the location of your presigned URL.

Webhook Delivery Behavior

To integrate reliably, follow these rules:

• PDFBolt sends exactly one webhook per conversion – on success, or after all conversion retries fail.
• retryDelays retries the conversion attempt itself, not webhook delivery.
• Store the requestId returned by the API so you can match each webhook to the original conversion request.
• If your webhook endpoint is unavailable when PDFBolt sends the callback (timeout, 5xx, network error), the delivery is not automatically retried. Inspect your Dashboard if the webhook never arrives.
• After verifying the signature, return a fast 200 OK response and run any slow follow-up work in your own background job.

For the full delivery contract, see Webhook Delivery Behavior in the endpoint reference.