Skip to main content

Async Workflow Details

Asynchronous conversion in PDFBolt allows you to process multiple documents simultaneously without waiting for each one to complete before starting the next. This method is particularly beneficial when dealing with large volumes of documents, as it significantly improves efficiency and throughput.


Here's a visual representation of the asynchronous flow:


S3 BucketWebhook EndpointPDFBoltClientS3 BucketWebhook EndpointPDFBoltClientPOST /async with webhook URL Return requestId Process PDF in background Upload PDF (to your S3 if custom URL provided) POST notification with documentUrl Retrieve PDF from documentUrl

How the Asynchronous Flow Works​

1. Submit Request​

  • Send a POST request to the /async endpoint.
  • Include the required parameter webhook, which is the URL where you want to receive a callback once processing is complete.
  • For more details on request parameters, refer to:
Request Example:
{
  "url": "https://example.com",
  "webhook": "https://your-app.com/endpoint"
}

2. Immediate Acknowledgment​

  • The API responds immediately with a requestId, confirming that your request has been received.
  • This allows your application to continue executing without waiting for the PDF generation to complete.
Response Example:
{
  "requestId": "7e075770-9c50-4018-a877-fc45c45b7850"
}

3. Parallel Processing​

  • PDFBolt processes documents in the background.
  • Multiple documents can be processed simultaneously, improving efficiency and reducing overall processing time.

4. Direct S3 Upload (Optional)​

  • If you provide a customS3PresignedUrl, the generated PDF will be uploaded directly to your S3‑compatible bucket.
  • If no URL is provided, the PDFs will be temporarily stored in our bucket for up to 24 hours.
  • Using customS3PresignedUrl is recommended ensuring secure and direct access within your storage environment.

5. Webhook Notification​

  • Once the PDF is generated, PDFBolt sends a POST request to your specified webhook URL.
  • The callback provides detailed information about the conversion process.
Webhook Request Example:
{
  "requestId": "b32bb5ce-483a-44ab-9239-52c0e3b0ff6c",
  "status": "SUCCESS",
  "errorCode": null,
  "errorMessage": null,
  "documentUrl": null,
  "expiresAt": "2024-12-30T21:05:38Z",
  "isAsync": true,
  "duration": 1403,
  "documentSizeMb": 0.04,
  "isCustomS3Bucket": true
}

Refer to the more examples and webhook request parameters for a complete list of fields and their descriptions.

6. Document Retrieval​

  • If you did not provide a customS3PresignedUrl, you can retrieve the PDF using the documentUrl provided in the callback.
  • If you provided a customS3PresignedUrl, the PDF will be available directly in your own S3 bucket for immediate access.

Benefits of Asynchronous Conversion​

  • Improved Efficiency: Avoid waiting for each PDF to generate before sending the next request. This allows you to process large batches more quickly and effectively.

  • Parallel Processing: Process multiple documents simultaneously, optimizing resource utilization and minimizing delays.

  • Non-Blocking Operations: Keep your application responsive, as it doesn't need to wait for the API to complete processing each request.

  • Direct S3 Uploads: Use the customS3PresignedUrl parameter to upload PDFs directly to your S3 bucket, ensuring enhanced security, compliance, and control over your data.