Skip to main content

Async Conversion

The /v1/async endpoint accepts a request, immediately returns a requestId, then delivers the result via HMAC-signed webhook callback once the PDF is ready. Use it when you want PDFBolt to process the conversion in the background and notify your application via webhook. The webhook parameter is mandatory.

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 mandatory webhook URL:

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

Failure Example​

If the conversion fails (e.g., timeout, invalid URL, target server error), the webhook callback delivers a JSON object with status: "FAILURE" and an errorCode. See Error Handling for all error codes and recommended actions.

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

Body Parameters​

Common Parameters

Below are only the parameters specific to the /async endpoint. For common parameters shared across all endpoints, see Conversion Parameters.

webhook​

Type: string

Required: Yes

Details: Your webhook endpoint URL where PDFBolt delivers the conversion result. The endpoint must accept POST requests.

Validation rules:

  • HTTPS only (HTTP is rejected).
  • Maximum length: 2048 characters.
  • Must be a publicly reachable domain. 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 URL for direct upload to your S3-compatible bucket. The URL must be no longer than 2048 characters. When provided, the webhook callback's documentUrl is null and isCustomS3Bucket: true (file goes directly to your bucket). If not provided, the document is stored in PDFBolt's 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://your-bucket.s3.amazonaws.com/document.pdf?<presigned-query-params>"
}

additionalWebhookHeaders​

Type: object

Required: No

Details: Includes custom headers in webhook callbacks. Use this parameter 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.
  • Combined header key/value size must not exceed 4KB.
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<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. Total attempts = 1 (initial) + length of 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).
  • 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 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
  • 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/parameters#timeout, https://pdfbolt.com/docs/parameters#waituntil and https://pdfbolt.com/docs/parameters#waitforfunction parameters.
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_89878444-79a5-4115-beeb-f36745d61cf7_2026-04-30T10-47-03Z.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 null2026-05-01T10:47:03Z
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 number574
documentSizeMbnumber
  • Size of the document in megabytes.
  • Will be null if status is FAILURE.
Any positive number or null0.02
isCustomS3Bucketboolean
  • Indicates if the generated document was uploaded to a user-provided custom S3 bucket or PDFBolt's default storage.
true
false		false

Webhook Delivery Behavior​

PDFBolt sends exactly one webhook per conversion — on success, or after all retries fail. retryDelays retries the conversion attempt itself – it does not retry webhook delivery.

If your webhook endpoint is unavailable when PDFBolt sends the callback (timeout, 5xx, network error), the delivery is not automatically retried. 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 200 OK 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 your Dashboard, on the API Keys page, under Webhook Signature.

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.
  • 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​