Conversion Webhook Callbacks & Job Notifications#

EnConvert notifies you when asynchronous and batch conversion jobs complete through three independent mechanisms: polling GET /v1/convert/batch/{batch_id}, webhook callbacks via the callback_url parameter, and email notifications via notification_email. All three can be combined in a single request, and finished files are retrieved through download URLs in the batch status response. This page documents the callback payloads, delivery requirements, and plan gating for each method.

Overview#

All three methods work for both single-URL async jobs and multi-URL batch jobs across the url-to-pdf, url-to-screenshot, website-to-pdf, and website-to-screenshot endpoints.

Batch Status Polling#

The recommended way to track job progress. Poll the batch status endpoint with the batch_id returned in the initial 202 response.

GET /v1/convert/batch/{batch_id}
X-API-Key: sk_live_your_private_key

Response#

{
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "processing",
    "total": 3,
    "completed": 1,
    "failed": 0,
    "in_progress": 2,
    "output_mode": "individual",
    "zip_download_url": null,
    "items": [
        {
            "source_url": "https://example.com/page-1",
            "status": "Success",
            "download_url": "https://spaces.example.com/...",
            "output_file_size": 184320,
            "duration": "3.12"
        },
        {
            "source_url": "https://example.com/page-2",
            "status": "In Progress",
            "download_url": null,
            "output_file_size": null,
            "duration": null
        }
    ]
}

Status Values#

In ZIP mode (output_mode: "zip"), a zip_download_url is provided for the entire archive when complete. In individual mode, each item has its own download_url.

For full response schema details, see Batch Processing.

Email Notifications#

Include the notification_email parameter in your request to receive an email when the job completes. If you omit this parameter, the email is sent to the project owner's email address by default.

Example#

curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \
  -H "X-API-Key: sk_live_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "async_mode": true,
    "notification_email": "[email protected]"
  }'

Response (HTTP 202 Accepted)#

{
    "status": "processing",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "url_count": 1,
    "output_format": "individual"
}

Email Content#

The completion email includes:

• Status header with a colored banner (green for success, red for failure)
• Job ID and Batch ID (if part of a batch)
• Status text (success or failed)
• Static text directing users to download files from their dashboard
• Tasks table (ZIP mode batch jobs only) with columns: #, URL (truncated to 50 characters), status, and output filename

In individual mode (including multi-URL individual batches), each per-URL email contains only the job ID and status -- no tasks table. In ZIP mode, the single batch email includes the full tasks table with all URLs and their statuses.

Webhook Callbacks#

Include the callback_url parameter in your request to receive a webhook POST when the job completes. Requires a plan with webhook access.

Example#

curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \
  -H "X-API-Key: sk_live_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "async_mode": true,
    "callback_url": "https://yourapp.com/webhooks/enconvert"
  }'

Response (HTTP 202 Accepted)#

{
    "status": "processing",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "url_count": 1,
    "output_format": "individual"
}

Single URL / Individual Mode Callback Payload#

In individual mode, a separate POST is sent for each URL as it completes:

{
    "job_id": "12345",
    "status": "success",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "gcs_uri": "env/files/{project_id}/url-to-pdf/example_20260405_123456789.pdf",
    "filename": "example_20260405_123456789.pdf",
    "file_size": 184320
}

For a failed conversion:

{
    "job_id": "12345",
    "status": "failed",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000"
}

ZIP Mode Callback Payload#

In ZIP mode, a single POST is sent when the entire batch completes:

{
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "success",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "gcs_uri": "env/files/{project_id}/url-to-pdf/batch_20260405_123456789.zip",
    "filename": "batch_20260405_123456789.zip",
    "file_size": 456789,
    "total_tasks": 3,
    "successful_tasks": 2,
    "failed_tasks": 1,
    "tasks": [
        {"url": "https://example.com/page-1", "status": "success", "filename": "page1.pdf"},
        {"url": "https://example.com/page-2", "status": "success", "filename": "page2.pdf"},
        {"url": "https://invalid-url.example", "status": "failed", "error": "Page load timeout"}
    ]
}

Using Multiple Notification Methods Together#

You can combine polling, email, and webhook in the same request. All three work independently.

curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \
  -H "X-API-Key: sk_live_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": [
      "https://example.com/page-1",
      "https://example.com/page-2"
    ],
    "notification_email": "[email protected]",
    "callback_url": "https://yourapp.com/webhooks/enconvert"
  }'

After submitting, you can: 1. Poll GET /v1/convert/batch/{batch_id} for real-time progress 2. Receive a webhook POST at your callback URL when each conversion finishes 3. Receive an email at the specified address when each conversion finishes

Notification Parameters#

Webhook Delivery Requirements#

Subscription Plan Gating#

Testing Webhooks#

During development, use webhook.site to generate a temporary callback URL for testing:

curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \
  -H "X-API-Key: sk_live_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "async_mode": true,
    "callback_url": "https://webhook.site/your-unique-id"
  }'

Visit your webhook.site dashboard to inspect the exact callback payload once the job completes.

Frequently asked questions#

How do I get a webhook callback when a file conversion job completes?#

Include the callback_url parameter in your request with a private API key. EnConvert sends a POST with Content-Type: application/json to that URL when the job completes. Webhook callbacks require a plan with webhook access (Pro or Enterprise).

Does EnConvert retry failed webhook deliveries?#

No. Your endpoint must respond within 30 seconds with HTTP 200, 201, 202, or 204. If delivery fails, results remain available via batch status polling at GET /v1/convert/batch/{batch_id}.

Can I use email, webhook, and polling notifications together?#

Yes. notification_email, callback_url, and status polling all work independently and can be combined in the same request. If notification_email is omitted, the completion email defaults to the project owner's email address.

Why do I receive one webhook per URL instead of one for the whole batch?#

In individual mode you receive N separate webhook POSTs (one per URL) and N separate emails. To receive a single webhook and email for the entire batch, use ZIP mode, which sends one POST with total_tasks, successful_tasks, failed_tasks, and a tasks array.

How can I test webhook callbacks during development?#

Use webhook.site to generate a temporary URL and pass it as callback_url in your request. The webhook.site dashboard shows the exact JSON payload EnConvert delivers when the job completes.