Async Conversion

The async conversion endpoint processes your request and immediately acknowledges receipt. Once rendering is complete, it sends a callback to the specified webhook, notifying you of the completion.

This method is ideal for handling large-scale document generation, especially when combined with uploading to your S3 storage. The webhook parameter is mandatory in the request body.

Endpoint Details

Method: POST

https://api.pdfbolt.com/v1/async

Success Example

Request

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

Response

{
  "requestId": "b32bb5ce-483a-44ab-9239-52c0e3b0ff6c"
}

Webhook Request

{
  "requestId": "b32bb5ce-483a-44ab-9239-52c0e3b0ff6c",
  "status": "SUCCESS",
  "errorCode": null,
  "errorMessage": null,
  "documentUrl": "https://s3.pdfbolt.com/pdfbolt_dd3f57ef-ea17-48a9-930a-8990ee7f52a7_2024-12-30T14-26-23Z.pdf",
  "expiresAt": "2024-12-30T21:05:38Z",
  "isAsync": true,
  "duration": 1403,
  "documentSizeMb": 0.04,
  "isCustomS3Bucket": false
}

Failure Example

Request

{
  "url": "https://example.com",
  "webhook": "https://your-example-webhook.com",
  "waitForFunction": "() => document.body.innerText.includes('Ready to Download')"
}

Response

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

Webhook Request

{
  "requestId": "7e075770-9c50-4018-a877-fc45c45b7850",
  "status": "FAILURE",
  "errorCode": "CONVERSION_TIMEOUT",
  "errorMessage": "Conversion process timed out. Please see https://pdfbolt.com/docs for optimization tips.",
  "documentUrl": null,
  "expiresAt": null,
  "isAsync": true,
  "duration": 32150,
  "documentSizeMb": null,
  "isCustomS3Bucket": false
}

Body Parameters

info

In this section, you will find only the parameters specific to the /async endpoint. To view the list of common parameters shared across all endpoints, please refer to the Conversion Parameters section.

webhook

Type: string

Required: Yes

Details: The webhook parameter specifies the URL of your application's endpoint to receive document URLs and additional details. It must be a valid, publicly accessible URL that can process incoming requests from our service.

Usage:

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

customS3PresignedUrl

Type: string

Required: No

Details: The customS3PresignedUrl allows you to specify a URL for direct upload to your S3 bucket. If not provided, the document is stored in our S3 bucket for 24 hours. See Uploading to Your S3 Bucket for setup details.

Usage:

{
  "url": "https://example.com",
  "webhook": "https://your-app.com/endpoint",
  "customS3PresignedUrl": "https://s3-your-custom-bucket.com?token=abcdef"
}

contentDisposition

Type: string

Required: No

Default Value: inline

Details: This parameter defines how the content is presented when downloaded from the S3 bucket:

• inline - displays the PDF directly in the browser.
• attachment - prompts the user to download the PDF as a file with a Save As dialog.

Usage:

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

additionalWebhookHeaders

Type: object

Required: No

Details: This parameter allows you to include up to 10 custom headers in asynchronous webhook requests, providing additional information as needed.

Usage:

{
  "url": "https://example.com",
  "webhook": "https://your-app.com/endpoint",
  "additionalWebhookHeaders": {
    "X-Custom-Header-1": "Value1",
    "X-Custom-Header-2": "Value2"
    // up to 10 headers
  }
}

tip

The additionalWebhookHeaders parameter can be used to:

• Add additional context about the request.
• Personalize webhook responses with custom headers.
• Assist in debugging and tracking requests effectively.

Response Parameters

Parameter	Type	Description	Possible Values	Example Value
requestId	string (UUID)	Unique identifier for the request.	Any valid UUID	ee57bcb5-b02b-4ae7-af37-6e91549f647d

Webhook Request Parameters

Parameter	Type	Description	Possible Values	Example Value
requestId	string (UUID)	Unique identifier for the request.	Any valid UUID	ee57bcb5-b02b-4ae7-af37-6e91549f647d
status	string (Enum)	Status of the request.	SUCCESS FAILURE	SUCCESS
errorCode	string	Error code if the request failed. Will be null if status is SUCCESS.	Refer to errorCode values in the HTTP Status Codes table for all possible values	CONVERSION_TIMEOUT
errorMessage	string	Error message if the request failed. Will be null if status is SUCCESS.	Any string or null	Conversion process timed out. Please see https://pdfbolt.com/docs for optimization tips.
documentUrl	string (URL)	URL to the generated document. Will be null if customS3PresignedUrl is provided. Will be null if status is FAILURE.	Any valid URL or null	https://s3.pdfbolt.com/pdfbolt_dd3f57ef-ea17-48a9-930a-8990ee7f52a7_2024-12-30T14-26-23Z.pdf
expiresAt	string (ISO 8601)	Expiration date and time of the document. Will be null if customS3PresignedUrl is provided. Will be null if status is FAILURE.	ISO 8601 datetime string in UTC or null	2024-12-31T16:45:01Z
isAsync	boolean	Indicates if the operation is asynchronous. Will always be true for the /async endpoint.	true	true
duration	number	Total processing time for the request. Measured in milliseconds.	Any positive number	1261
documentSizeMb	number	Size of the document in megabytes. Will be null if status is FAILURE.	Any positive number or null	0.36
isCustomS3Bucket	boolean	Indicates if the generated document was uploaded to a user-provided custom S3 bucket or PDFBolt's default storage.	true false	false