Skip to main content

Async Conversion

The async conversion endpoint processes your request and immediately acknowledges receipt. Once generation 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​

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

Failure Example​

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

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"
}

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"
  }
}
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.

retryDelays​

Type: Array<number>

Required: No

Details: The retryDelays parameter defines a custom retry schedule for failed conversions. Each element is the delay in minutes before the next retry attempt, measured from the last failed attempt. The total number of attempts equals the initial attempt plus the number of elements in the retryDelays array.

Validation rules:

  • Array of positive integers (minutes), floats are rejected.
  • Minimum 1 element, maximum 5 elements (empty array is rejected).
  • Values must be in strictly ascending order (e.g., [5, 5, 10] is rejected).
  • All values must be greater than 0.
  • Maximum value per element: 1440 (24 hours).
Retry behavior
  • Webhooks are sent only on final failure or success. Intermediate retry failures do not trigger a webhook callback.
  • Only successful conversions consume credits, regardless of how many retries occur.

Usage:

{
  "url": "https://example.com",
  "webhook": "https://your-app.com/endpoint",
  "retryDelays": [1, 5, 15]
}

In the example above, there are 4 total attempts (1 initial + 3 retries). If the first conversion attempt fails:

  • Retry 1: 1 minute after the first failure.
  • Retry 2: 5 minutes after retry 1 fails.
  • Retry 3: 15 minutes after retry 2 fails.
  • If all retries fail, the webhook is called with FAILURE status.

Response Parameters​

ParameterTypeDescriptionPossible ValuesExample Value
requestIdstring (UUID)
  • Unique identifier for the request.
Any valid UUIDee57bcb5-b02b-4ae7-af37-6e91549f647d

Webhook Request Parameters​

ParameterTypeDescriptionPossible ValuesExample Value
requestIdstring (UUID)
  • Unique identifier for the request.
Any valid UUIDee57bcb5-b02b-4ae7-af37-6e91549f647d
statusstring (Enum)
  • Status of the request.
SUCCESS
FAILURE		SUCCESS
errorCodestring
  • 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 valuesCONVERSION_TIMEOUT
errorMessagestring
  • Error message if the request failed.
  • Will be null if status is SUCCESS.
Any string or nullConversion process timed out. Please see https://pdfbolt.com/docs for optimization tips.
documentUrlstring (URL)
  • URL to the generated document.
  • Will be null if customS3PresignedUrl is provided.
  • Will be null if status is FAILURE.
Any valid URL or nullhttps://s3.pdfbolt.com/pdfbolt_dd3f57ef-ea17-48a9-930a-8990ee7f52a7_2024-12-30T14-26-23Z.pdf
expiresAtstring (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 null2024-12-31T16:45:01Z
isAsyncboolean
  • Indicates if the operation is asynchronous.
  • Will always be true for the /async endpoint.
truetrue
durationnumber
  • Total processing time for the request.
  • Measured in milliseconds.
Any positive number1261
documentSizeMbnumber
  • Size of the document in megabytes.
  • Will be null if status is FAILURE.
Any positive number or null0.36
isCustomS3Bucketboolean
  • Indicates if the generated document was uploaded to a user-provided custom S3 bucket or PDFBolt's default storage.
true
false		false

Webhook Signature Verification​

Each webhook request includes an x-pdfbolt-signature header, so you can confirm it genuinely came from PDFBolt. The signature is an HMAC-SHA256 hash formatted as:

x-pdfbolt-signature: sha256=<hex-encoded-hmac>

How It Works​

  1. PDFBolt computes HMAC-SHA256(webhook_signature_key, raw_request_body) using your webhook signature key.
  2. The result is hex-encoded and prefixed with sha256=.
  3. The signature is sent in the x-pdfbolt-signature header of every webhook request (both success and failure).

Finding Your Webhook Signature Key​

You'll find your webhook signature key in the Dashboard – look for the Webhook Signature section on the API Keys page.

Webhook Signature Key

Verification Examples​

Signature verification
  • Always compute the HMAC from the raw request body – before any JSON parsing. If you parse and re-serialize the JSON, key ordering or whitespace may change, producing a different hash.
  • Make sure to use a constant-time comparison function to prevent timing attacks.
const crypto = require('crypto');

function verifyWebhookSignature(rawBody, signatureHeader, webhookSignatureKey) {
    const expected = 'sha256=' + crypto
        .createHmac('sha256', webhookSignatureKey)
        .update(rawBody, 'utf8')
        .digest('hex');

    const expectedBuf = Buffer.from(expected);
    const receivedBuf = Buffer.from(signatureHeader);

    if (expectedBuf.length !== receivedBuf.length) {
        return false;
    }

    return crypto.timingSafeEqual(expectedBuf, receivedBuf);
}