Webhook & Download

Asynchronous processing and external file delivery.

Webhooks

By default, requests are synchronous: you send a file and wait for the PDF. For large files or batch operations, add webhook headers to switch to async:

1. Gotenberg validates the request and returns 204 No Content.
2. The conversion runs in the background.
3. The result is POSTed to your Gotenberg-Webhook-Url.

See the Webhook module configuration for retries, timeouts, and allowed URLs. Tools like PipeDream or Webhook.site are great for testing.

POST/forms/...

Headers

Gotenberg-Webhook-Urlstringrequired

The callback URL where the successful result will be sent via POST (default).

Default:None

Gotenberg-Webhook-Error-Urlstring

Deprecated. The callback URL to use if the conversion fails. Not required when Gotenberg-Webhook-Events-Url is set.

Default:None

Gotenberg-Webhook-Methodstring

The HTTP method to use for the success callback (POST, PUT, PATCH).

Default:POST

Gotenberg-Webhook-Error-Methodstring

The HTTP method to use for the error callback.

Default:POST

Gotenberg-Webhook-Extra-Http-Headersstring

JSON object containing extra headers to send to the callback URLs.

Default:None

Gotenberg-Webhook-Events-Urlstring

A URL to receive structured JSON events after each webhook operation.

Default:None

Example Request

cURL

curl \
--request POST http://localhost:3000/forms/chromium/convert/url \
--header 'Gotenberg-Webhook-Url: https://my.webhook/success' \
--header 'Gotenberg-Webhook-Events-Url: https://my.webhook/events' \
--header 'Gotenberg-Webhook-Extra-Http-Headers: {"Authorization": "Bearer 123"}' \
--form url=https://my.url

Responses

204

The request is being processed asynchronously.

400

At least one of the header is invalid or missing.

Content-Type: text/plain; charset=UTF-8
Gotenberg-Trace: {trace}
Body: {error}

403

At least one of the specified URLs is forbidden.

Content-Type: text/plain; charset=UTF-8
Gotenberg-Trace: {trace}
Body: Forbidden

Success

The resulting file has been uploaded successfully to the specified URL.

Content-Disposition: attachment; filename={output-filename.ext}
Content-Type: {content-type}
Content-Length: {content-length}
Gotenberg-Trace: {trace}
User-Agent: Gotenberg
Body: {output-file}

Error

The operation failed and the error has been reported to the specified URL.

Content-Type: application/json; charset=UTF-8
Gotenberg-Trace: {trace}
User-Agent: Gotenberg
{
  "status": "{status}",
  "message": "{message}"
}

Webhook Events

Set the Gotenberg-Webhook-Events-Url header to receive structured JSON events after each webhook operation. Events fire after the main webhook callbacks and do not affect the result delivery.

Success event:

{
  "event": "webhook.success",
  "correlationId": "unique-request-id",
  "timestamp": "2025-01-15T10:30:00.000000000Z"
}

Error event:

{
  "event": "webhook.error",
  "correlationId": "unique-request-id",
  "timestamp": "2025-01-15T10:30:00.000000000Z",
  "error": {
    "status": 500,
    "message": "conversion failed"
  }
}

Delivery failures to the events URL are logged but do not cascade to the main webhook flow.

Download From

All multipart/form-data endpoints accept the downloadFrom form field. This allows you to instruct Gotenberg to fetch files from remote URLs (e.g., S3, Azure Blob, or an internal CDN) instead of uploading them directly.

Configuration

This feature is enabled by default. It can be disabled via the API_DISABLE_DOWNLOAD_FROM environment variable. For further details, refer to the API module configuration.

Object Structure

The downloadFrom field accepts a JSON-formatted array. Each item in the array must be an object with the following keys:

Key	Description	Default
url	URL of the file. The remote server MUST return a Content-Disposition header with a filename parameter.	Required
extraHttpHeaders	A JSON object containing extra HTTP headers to send when fetching this specific URL.	None
embedded	Whether this file should be embedded (legacy, prefer field).	false
field	Routes the downloaded file to a specific form field: "embedded", "watermark", or "stamp". When set, takes precedence over embedded.	"" (regular file)

Known Issue: Empty Media Types

Currently, a bug in Go prevents Gotenberg from parsing responses with an empty media type.

AWS S3 Users: Ensure your S3 objects have the Content-Disposition metadata set (e.g., attachment; filename="doc.pdf") to avoid this issue.

POST/forms/...

Form Fields

downloadFromjson

A JSON array of files to fetch remotely.

Default:None

Example Request

cURL

curl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form 'downloadFrom=[{
"url": "http://url/to/file.docx",
"extraHttpHeaders": {
  "X-My-Header": "MyValue"
}
}]' \
-o my.pdf

Sponsors

Powered by

❤️ Become a sponsor