Skip to main content

Async Conversion

The /v1/async endpoint accepts a PDF conversion request from a URL, HTML, or a published template with JSON data and immediately returns a requestId. PDFBolt processes the request in the background and sends the final result to your HMAC-signed webhook when the conversion succeeds or all conversion attempts fail. The webhook parameter is required.

Plan requirement

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

Endpoint Details​

Method: POST

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

Success Example​

Example request body with the required webhook URL:

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

Failure Example​

Requests rejected before acceptance return an HTTP error and do not trigger a webhook. After a request is accepted, a final conversion failure, such as a timeout or target page error, is delivered to the webhook with status: "FAILURE" and an errorCode. See Async Conversion Failures for recommended actions and the OpenAPI Reference for the exact schema.

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

Body Parameters​

Common Parameters

The parameters below configure /v1/async processing and webhook delivery. customS3PresignedUrl is also available on the /v1/sync endpoint. For parameters shared by all Conversion API endpoints, see Conversion Parameters.

webhook​

Type: string

Required: Yes

Details: The HTTPS URL to which PDFBolt sends the conversion result. It must accept POST requests and be publicly reachable.

Validation rules:

  • HTTPS only (HTTP is rejected).
  • Maximum length: 2048 characters.
  • Test domains (e.g., .test) are not accepted.

Usage:

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

customS3PresignedUrl​

Type: string

Required: No

Details: Specifies an HTTPS pre-signed PUT URL for direct upload to your S3-compatible bucket. The URL must be no longer than 2048 characters. When provided, the webhook reports documentUrl and expiresAt as null, and isCustomS3Bucket as true. If not provided, the document is stored in PDFBolt's temporary storage 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://your-bucket.s3.amazonaws.com/document.pdf?<presigned-query-params>"
}

additionalWebhookHeaders​

Type: object

Required: No

Details: Adds custom headers to webhook callbacks. Use them to pass context to your webhook endpoint.

Validation rules:

  • JSON object with string keys and string values.
  • Header values cannot be null.
  • Maximum 10 headers.
  • The combined UTF-8 size of all header names and values must not exceed 4 KB.
Reserved headers

Set automatically by PDFBolt – do not include: Content-Type, x-pdfbolt-signature, x-pdfbolt-conversion-cost.

Usage:

{
  "url": "https://example.com",
  "webhook": "https://your-app.com/endpoint",
  "additionalWebhookHeaders": {
    "X-Custom-Header-1": "Value1",
    "X-Custom-Header-2": "Value2"
  }
}
Common Use Cases

Use additionalWebhookHeaders to:

  • Add tenant or environment identifiers (e.g., X-Tenant-Id, X-Environment).
  • Forward user or session context (e.g., X-User-Id).
  • Include correlation IDs for request tracing across services.

retryDelays​

Type: Array<integer>

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. Total attempts = 1 (initial) + length of the retryDelays array.

Validation rules:

  • Array of positive integers in minutes. Floating-point values 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).
  • Maximum value per element: 1440 (24 hours).
Retry Behavior
  • PDFBolt attempts the webhook only after a conversion succeeds or all retries fail. Intermediate retry failures do not trigger a 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 any attempt succeeds, the webhook is called immediately with SUCCESS status and remaining retries are skipped.
  • 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 UUID4da0a428-16e0-4c95-b1d3-a8f475ed717e

Webhook Request Parameters​

ParameterTypeDescriptionPossible ValuesExample Value
requestIdstring (UUID)
  • Unique identifier for the request.
Any valid UUID4da0a428-16e0-4c95-b1d3-a8f475ed717e
statusstring (Enum)
  • Status of the request.
SUCCESS
FAILURE		SUCCESS
errorCodestring or null
  • 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 or null
  • 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/parameters#timeout, https://pdfbolt.com/docs/parameters#waituntil and https://pdfbolt.com/docs/parameters#waitforfunction parameters.
documentUrlstring (URL) or null
  • 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_89878444-79a5-4115-beeb-f36745d61cf7_2026-04-30T10-47-03Z.pdf
expiresAtstring (ISO 8601) or null
  • 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 null2026-05-01T10:47:03Z
isAsyncboolean
  • Indicates if the operation is asynchronous.
  • Will always be true for the /v1/async endpoint.
truetrue
durationinteger
  • PDF conversion time in milliseconds.
Any non-negative integer574
documentSizeMbnumber or null
  • Size of the document in megabytes.
  • Will be null if status is FAILURE.
Any non-negative number or null0.02
isCustomS3Bucketboolean
  • Whether the async conversion request used a user-provided S3-compatible bucket.
true
false		false

Webhook Delivery Behavior​

PDFBolt attempts one webhook callback per accepted conversion – after the conversion succeeds or all retries fail. retryDelays retries the conversion attempt itself – it does not retry webhook delivery.

If webhook delivery fails because of a timeout, a 5xx response, or a network error, PDFBolt does not retry it automatically. To investigate:

  • Check the conversion status in your Dashboard using the requestId.
  • Review the Webhook Result column in the Dashboard – it shows the HTTP response code returned by your endpoint. Unreachable means the delivery failed (timeout or network error).

Recommended client-side practices:

  • After verifying the signature, return a fast 2xx response and run any slow follow-up work in your own background job.
  • Make your handler idempotent – use requestId as a deduplication key.
  • Monitor your endpoint uptime; if it goes down, expect missed deliveries during the outage.

For response and webhook headers, see API Response Headers.

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​

Find your webhook signature key in the Webhook Signature section of the API Credentials page in your Dashboard.

Webhook Signature section on the API Credentials page

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.
  • 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);
}
Framework Setup

Each framework reads request bodies differently. Here's how to access raw bytes for HMAC verification:

Go (Gin, Echo) and Rust (Axum, Actix-web) read raw body by default – no setup needed.

Next Steps​