Job Notifications

Enconvert supports three mechanisms for tracking asynchronous and batch jobs: batch status polling, email notifications, and webhook callbacks. You can use any combination to be alerted when a conversion job completes.

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": "team@yourcompany.com"
  }'

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": "team@yourcompany.com",
    "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.