Job Notifications

Enconvert supports two notification mechanisms for asynchronous and batch jobs: email notifications and customer callback webhooks. You can use either or both to be alerted when a conversion job completes.

Overview

Both notification types are triggered when the job finishes, regardless of whether the job succeeded or failed.

Email Notifications

Include the notification_email parameter in your request to receive an email when the job completes.

Example: Single URL with Async Mode

curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \
  -H "Authorization: Bearer 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

{
  "success": true,
  "message": "Job queued. You will be notified at team@yourcompany.com when complete.",
  "job_id": "job_5e2f8a1b",
  "status": "processing"
}

Email Content

When the job completes, the specified email address receives a message containing:

• The job ID and final status (success or failed)
• The original URL(s) submitted
• A presigned download link for each successfully converted file
• Error details for any failed tasks
• The conversion time and file size for each result

Customer Callback Webhooks

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

Example: Single URL with Callback

curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \
  -H "Authorization: Bearer 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

{
  "success": true,
  "message": "Job queued. Results will be sent to your callback URL.",
  "job_id": "job_9c4d3f7a",
  "status": "processing"
}

Single Job Callback Payload

When the single-URL job completes, Enconvert sends a POST request to your callback_url with the following JSON body:

{
  "job_id": "job_9c4d3f7a",
  "status": "completed",
  "total_tasks": 1,
  "completed_tasks": 1,
  "failed_tasks": 0,
  "tasks": [
    {
      "url": "https://example.com",
      "status": "success",
      "presigned_url": "https://storage.enconvert.com/live/files/abc123/url-to-pdf/example-com.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...",
      "object_key": "live/files/abc123/url-to-pdf/example-com.pdf",
      "file_size": 184320,
      "conversion_time": 3.72
    }
  ]
}

Bulk Job Callback Payload

When a batch job completes, the callback payload includes details for every task in the batch:

{
  "job_id": "batch_7f3a9c2e",
  "status": "completed",
  "total_tasks": 3,
  "completed_tasks": 2,
  "failed_tasks": 1,
  "tasks": [
    {
      "url": "https://example.com/page-1",
      "status": "success",
      "presigned_url": "https://storage.enconvert.com/live/files/abc123/url-to-pdf/page-1.pdf?X-Amz-Algorithm=...",
      "object_key": "live/files/abc123/url-to-pdf/page-1.pdf",
      "file_size": 184320,
      "conversion_time": 3.12
    },
    {
      "url": "https://example.com/page-2",
      "status": "success",
      "presigned_url": "https://storage.enconvert.com/live/files/abc123/url-to-pdf/page-2.pdf?X-Amz-Algorithm=...",
      "object_key": "live/files/abc123/url-to-pdf/page-2.pdf",
      "file_size": 210944,
      "conversion_time": 4.55
    },
    {
      "url": "https://invalid-url.example",
      "status": "failed",
      "error": "Failed to load page: net::ERR_NAME_NOT_RESOLVED"
    }
  ]
}

Using Both Notifications Together

You can include both notification_email and callback_url in the same request. The email and webhook are sent independently when the job completes.

Example

curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \
  -H "Authorization: Bearer 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"
  }'

Both the email notification and webhook callback will be triggered when the batch completes.

Notification Parameters

Webhook Requirements

Your callback endpoint must meet the following requirements:

Important Notes

• Notifications are only sent when a job finishes (all tasks completed or failed). In-progress updates are not sent.
• If the webhook delivery fails, the job results are still available via the GET /v1/convert/status/{job_id} endpoint.
• Email notifications may take a few seconds to arrive after job completion, depending on email delivery.
• For batch jobs, a single notification is sent when all tasks in the batch have finished, not per individual task.
• The presigned_url values in notifications are temporary and will expire. Download the files promptly after receiving the notification.

Testing Webhooks

During development, you can use webhook.site to generate a temporary callback URL for testing. This allows you to inspect the exact payload Enconvert sends without setting up your own server.

curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \
  -H "Authorization: Bearer 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 see the callback payload once the job completes.