Webhooks

Receive async result

PDFBolt sends this webhook to the URL provided in the webhook parameter of an async conversion request. PDFBolt attempts one callback for each accepted async conversion: after the conversion succeeds or after all configured conversion retries fail. Verify the x-pdfbolt-signature header with your webhook signature key before trusting the payload.

postWebhookasyncConversionResult

Headers

x-pdfbolt-signaturestring required
Example:sha256=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

HMAC-SHA256 signature of the raw webhook request body, prefixed with sha256= and encoded as lowercase hex. Verify the exact bytes received in the HTTP body before parsing or re-serializing JSON.

x-pdfbolt-conversion-costinteger required
Example:1

Number of document credits charged for the conversion. For failed conversions, PDFBolt sends 0.

Payload

requestIdstring uuid required

Unique identifier for the async conversion request.

status'SUCCESS' | 'FAILURE' required

Final async conversion status.

errorCode'BAD_REQUEST' | 'FORBIDDEN' | 'PDF_SIZE_TOO_LARGE' | 'TEMPLATE_EVAL_ERROR' | 'CUSTOM_S3_UPLOAD_ERROR' | 'TARGET_CLOSED' | 'NO_BROWSER_CONTEXT' | 'URL_NOT_RESOLVED' | 'PDF_PRINTING_FAILED' | 'CONVERSION_TIMEOUT' | 'UNEXPECTED_ERROR' | 'INVALID_CREDENTIALS' | 'HTTP_RESPONSE_FAILURE' | 'UNPROCESSABLE_ENTITY' required

Final async conversion error code.

errorMessagestring nullable required

Error message if the conversion failed, otherwise null.

documentUrlstring uri nullable required

URL to the generated PDF, or null for failed conversions or custom S3 uploads.

expiresAtstring date-time nullable required

Expiration timestamp for PDFs in PDFBolt's temporary storage, or null for failed conversions or custom S3 uploads.

isAsynctrue required

Always true for async webhook callbacks.

durationinteger required

PDF conversion time for the final attempt, in milliseconds.

documentSizeMbnumber nullable required

Generated document size in megabytes, or null for failed conversions.

isCustomS3Bucketboolean required

Whether the async conversion request used a user-provided S3-compatible bucket.

Response

Your webhook endpoint should return a successful 2xx response after accepting the callback.

Changes

Webhooks have no change history: a webhook is keyed by its event name rather than a path and method, so no recorded change can name it.