Callback notifications

The callback parameter allows you to configure a notification endpoint that will be called when asynchronous rendering is complete.

​

Overview

When rendering PDFs asynchronously, you may want to be notified when the process is complete. The callback parameter lets you specify a URL that will receive a notification with details about the completed rendering.

​

Parameter details

​

Usage

{
  "parts": "https://example.com",
  "destination": {
    "provider": "aws_s3",
    "bucket": "my-pdf-bucket",
    "path": "reports/document.pdf"
  },
  "callback": {
    "url": "https://myapp.com/callbacks/pdf-complete"
  }
}

​

Behavior

When your asynchronous rendering job completes, the API will:

1. Send a POST request to the specified callback URL
2. Include information about the rendering job status and the location of the generated PDF
3. Include any custom headers you specified in the request

​

Callback payload

The callback will receive a JSON payload with information about the completed rendering job, including:

{
  "status": "completed",
  "destination": {
    "provider": "aws_s3",
    "bucket": "my-pdf-bucket",
    "path": "reports/document.pdf"
  },
  "job_id": "job_123456789",
  "completed_at": "2023-04-01T12:34:56Z"
}

​

Use cases

This parameter is particularly useful for:

1. Workflow automation: Trigger subsequent processes once the PDF is ready
2. User notifications: Alert users when their requested document is available
3. System integration: Update your application’s state based on PDF generation status

​

Example with custom headers

{
  "parts": "https://example.com",
  "destination": {
    "provider": "aws_s3",
    "bucket": "my-pdf-bucket",
    "path": "reports/document.pdf"
  },
  "callback": {
    "url": "https://myapp.com/callbacks/pdf-complete",
    "headers": {
      "Authorization": "Bearer your-secret-token",
      "X-Custom-Header": "custom-value"
    }
  }
}

​

Security considerations

When using callbacks:

1. Use HTTPS: Always use HTTPS URLs for your callback endpoints
2. Validate requests: Include authentication headers and verify them in your callback handler
3. Implement retry logic: Be prepared to handle callback delivery failures

​

Related parameters

The callback parameter is typically used with the destination parameter, which specifies where the rendered PDF will be stored. Together, they enable a fully asynchronous workflow for PDF generation.