---
title: "webhook_url parameter"
description: "Receive your generated image or PDF via webhook to avoid 30 second timeouts on long renders."
url: "https://html2img.com/docs/parameters/webhook-url/"
---

# 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

> **Important**
>
> We strongly recommend using webhooks for:
> - Screenshot API requests
> - Images with high DPI values (2-4)
> - Full page captures
> - Large viewport dimensions

## Examples

### Screenshot API Example (`https://app.html2img.com/api/screenshot`)
```json
{
    "url": "https://example.com",
    "webhook_url": "https://your-domain.com/webhook"
}
```

Initial Response:
```json
{
    "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`)
```json
{
    "html": "<h1>Large Content</h1>",
    "dpi": 3,
    "webhook_url": "https://your-domain.com/webhook"
}
```

### Webhook Responses

Webhook Success Response:
```json
{
    "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:
```json
{
    "status": "error",
    "error": "The request timed out. Please try again.",
    "filename": "image-1641234567890-123456.png",
    "log_id": "ab12345cd-6aa2-4927-9afe-012345abc123"
}
```

> **Warning**
>
> Your webhook endpoint should be publicly accessible, accept POST requests with JSON content, handle both success and error responses, and process the response asynchronously.

## 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](https://html2img.com/docs/examples/chart-screenshot/), [invoice-receipt example](https://html2img.com/docs/examples/invoice-receipt/), [getting started guide](https://html2img.com/docs/getting-started/).

## Templates that use this parameter

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

- [Invoice image template](https://html2img.com/templates/invoice-image/)
- [Certificate of completion template](https://html2img.com/templates/certificate-of-completion/)