Deliver with webhooks
Have Gotenberg upload results to your storage or service, instead of answering with them, and download its inputs from URLs.
Send a webhook
Two headers turn a request into a webhook:
curl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form files=@report.docx \
--header 'Gotenberg-Webhook-Url: https://example.com/upload' \
--header 'Gotenberg-Webhook-Events-Url: https://example.com/events'
HTTP/1.1 204 No Content
Gotenberg checks both URLs, then answers 204 No Content right away. Once the work is done, it uploads the result to Gotenberg-Webhook-Url, then posts an event to Gotenberg-Webhook-Events-Url. Both headers are required: one alone answers 400, naming the other. Each takes an absolute http or https URL with a host. Any other URL, or a host that doesn't resolve, answers 400 and names the header. A URL the filters refuse answers 403.
The upload
The upload is a POST of the result, with its Content-Type, a Content-Disposition that names the file, and the request's Gotenberg-Trace. Gotenberg-Webhook-Method makes it a PUT or a PATCH.
The events
A JSON webhook.success event follows a delivered upload. A failed request, or an upload that fails for good, sends webhook.error instead, with the status and the message the request would have answered:
{
"event": "webhook.error",
"correlationId": "my-request-42",
"timestamp": "2026-11-01T17:02:51.123456789Z",
"error": {
"status": 400,
"message": "Invalid form data: form field 'paperSize' is invalid (got 'A9', want A0, A1, A2, A3, A4, A5, B4, B5, Letter, Legal or Tabloid)"
}
}
When the upload itself fails for good, the message says what the webhook URL answered, or why Gotenberg couldn't reach it:
The webhook URL answered 500 Internal Server Error after 5 attempts
The webhook URL could not be reached after 5 attempts: the connection was refused
correlationId is the request's Gotenberg-Trace: set it to your own identifier to match events to requests.
Authenticate the calls
Gotenberg-Webhook-Extra-Http-Headers takes a JSON object of headers, which Gotenberg sends with the upload and the event:
curl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form files=@report.docx \
--header 'Gotenberg-Webhook-Url: https://example.com/upload' \
--header 'Gotenberg-Webhook-Events-Url: https://example.com/events' \
--header 'Gotenberg-Webhook-Extra-Http-Headers: {"Authorization": "Bearer abc123"}' \
--header 'Gotenberg-Trace: my-request-42'
Retries
An upload that can't connect, or that answers 429 or a 5xx, is tried four more times, waiting 1, 2, 4, then 8 seconds. Another 4xx isn't retried. --webhook-max-retry, --webhook-retry-min-wait and --webhook-retry-max-wait tune it.
Wait for the delivery
With --webhook-enable-sync-mode, Gotenberg answers the 204 only once the upload and the event are done. The AWS Lambda and Cloud Run images turn it on, since both may freeze or stop a container that has answered.
Download the inputs
downloadFrom lists URLs Gotenberg downloads before it starts, as if you had uploaded the files. Each server must answer with a Content-Disposition header that names the file:
curl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form 'downloadFrom=[
{ "url": "https://files.example.com/report.docx" }
]' \
-o report.pdf
An entry without an absolute http or https URL answers 400, naming downloadFrom and the entry's index, counted from 0. With webhooks, a request then carries no file at all. How requests work shows the headers each download can send.
Restrict the destinations
Webhooks and downloads reach any address by default. --webhook-deny-private-ips, --api-download-from-deny-private-ips and their allow and deny lists restrict them: see Secure Gotenberg.