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
Validation	Must be a valid URL - anything else fails with a 400 validation_error
API	Both HTML/CSS and Screenshot APIs

Description

When provided, the API will:

1. Immediately return a success response with a processing status, the render id and your remaining credits
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:

{
    "success": true,
    "id": "ab12345cd-6aa2-4927-9afe-012345abc123",
    "expires_at": null,
    "credits_remaining": 950,
    "status": "processing",
    "message": "Screenshot generation started",
    "url": "https://i.html2img.com/image-1641234567890-123456.png"
}

The url is where the image will land once the render completes - it is not live until your webhook fires. The id here is the same value your webhook later receives as log_id.

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

• Relying on webhook retries. Delivery is attempted once - if your endpoint is down, the callback is missed. You can still recover: the initial response already contains the final url, so poll it as a fallback.
• Webhook endpoint requires authentication. We do not send custom headers. Embed any secret in the URL itself or verify by the log_id, which matches the id from your initial response.
• 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.

Templates that use this parameter

Batch workflows often combine webhook delivery with high-volume templates:

• Invoice image template
• Certificate of completion template