Webhook URL Parameter

The webhook_url parameter enables asynchronous image generation, which is essential for the Screenshot API or larger images.

Specifications

Property	Value
Type	string
Required	No
Default	null
API	Both HTML/CSS and Screenshot APIs

Description

When provided, the API will:

1. Immediately return a success response with a processing status and filename
2. Continue processing the image in the background
3. Send a POST request to your webhook URL when the image is ready or if an error occurs

Examples

Screenshot API Example (https://app.html2img.com/api/screenshot)

{
    "url": "https://example.com",
    "webhook_url": "https://your-domain.com/webhook"
}

Initial Response:

{
    "message": "Screenshot generation started",
    "filename": "image-1641234567890-123456.png",
    "status": "processing",
    "log_id": "ab12345cd-6aa2-4927-9afe-012345abc123"
}

HTML API Example (https://app.html2img.com/api/html)

{
    "html": "<h1>Large Content</h1>",
    "dpi": 3,
    "webhook_url": "https://your-domain.com/webhook"
}

Webhook Responses

Webhook Success Response:

{
    "status": "success",
    "message": "Screenshot generated successfully",
    "url": "https://i.html2img.com/image-1641234567890-123456.png",
    "filename": "image-1641234567890-123456.png",
    "log_id": "ab12345cd-6aa2-4927-9afe-012345abc123",
    "dpi": 1
}

Webhook Error Response:

{
    "status": "error",
    "error": "The request timed out. Please try again.",
    "filename": "image-1641234567890-123456.png",
    "log_id": "ab12345cd-6aa2-4927-9afe-012345abc123"
}

Common values

• https://api.your-app.com/html2img/webhook - your own backend route, ideally with a shared secret in the URL.
• https://webhook.site/abc123 - a free temporary endpoint for testing during development.
• https://your-ngrok-url.ngrok.io/webhook - your local server exposed via ngrok during development.

When to use

Use webhook_url whenever the render is likely to exceed the 30 second sync timeout: high DPI, full-page captures, slow third-party pages, or any URL with heavy ads or JavaScript. Use it in production by default for the Screenshot API since you cannot predict how long an external page will take.

Common mistakes

• Webhook endpoint not idempotent. We retry once on a 5xx response. Make sure processing the same log_id twice has the same effect.
• Webhook endpoint requires authentication. We do not send custom headers. Embed any secret in the URL itself or verify by the log_id.
• Holding the request open after success. Return a 200 within a few seconds, then process asynchronously.

See also: chart-screenshot example, invoice-receipt example, getting started guide.