Skip to main content

Webhook & Download

Handle long-running processes or fetch external assets without keeping persistent connections open.

Webhooks​

By default, Gotenberg handles requests synchronously: you send a file, wait, and get a PDF back. However, for large files or batch operations, you may prefer an asynchronous workflow.

When Webhook headers are provided:

  1. Gotenberg immediately validates the request.
  2. Returns a 204 No Content response.
  3. Processes the conversion in the background.
  4. Uploads the resulting PDF to the URL specified in Gotenberg-Webhook-Url.
Configuration

You can customize retries, timeouts, and allowed URLs. See the Webhook module configuration for details.

Testing Webhooks

Tools like PipeDream or Webhook.site are excellent for testing these callbacks without setting up a dedicated server.

POST/forms/...
Headers
Gotenberg-Webhook-Urlstringrequired
The callback URL where the successful result will be sent via POST (default).
Default:None
Gotenberg-Webhook-Error-Urlstringrequired
The callback URL to use if the conversion fails.
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
Example Request
cURL
curl \
--request POST http://localhost:3000/forms/chromium/convert/url \
--header 'Gotenberg-Webhook-Url: https://my.webhook/success' \
--header 'Gotenberg-Webhook-Error-Url: https://my.webhook/error' \
--header 'Gotenberg-Webhook-Extra-Http-Headers: {"Authorization": "Bearer 123"}' \
--form url=https://my.url
Responses
The request is being processed asynchronously.

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:

KeyDescriptionDefault
urlURL of the file. The remote server MUST return a Content-Disposition header with a filename parameter.Required
extraHttpHeadersA JSON object containing extra HTTP headers to send when fetching this specific URL.None
embeddedWhether this file should be embedded.false
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
Responses
The JSON is malformed.
Content-Type: text/plain; charset=UTF-8
Gotenberg-Trace: {trace}
Body: {error}
TheCodingMachinepdfme
Powered by
DockerJetBrains
❤️ Become a sponsor