Webhook

The webhook feature lets Gotenberg asynchronously upload output files from multipart/form-data routes to a specified destination. The API immediately returns a 204 No Content response while the upload continues in the background.

It uses the following HTTP headers:

Header	Description	Default
Gotenberg-Webhook-Url	The callback to use.	required
Gotenberg-Webhook-Error-Url	The callback to use if error.	required
Gotenberg-Webhook-Method	The HTTP method to use (POST, PATCH, or PUT).	POST
Gotenberg-Webhook-Error-Method	The HTTP method to use if error (POST, PATCH, or PUT).	POST
Gotenberg-Webhook-Extra-Http-Headers	The extra HTTP headers to send to both URLs (JSON format).	None

Checkout the Webhook module configuration to tailor the Webhook feature to your needs.

info

PipeDream provides an excellent platform if you wish to test the webhook feature.

cURL

curl \
--request POST http://localhost:3000/forms/chromium/convert/url \
--header 'Gotenberg-Webhook-Extra-Http-Headers: {"MyHeader": "MyValue"}' \
--header 'Gotenberg-Webhook-Url: https://my.webhook.url' \
--header 'Gotenberg-Webhook-Method: PUT' \
--header 'Gotenberg-Webhook-Error-Url: https://my.webhook.error.url' \
--header 'Gotenberg-Webhook-Error-Method: POST' \
--form url=https://my.url

204 No Content

Gotenberg-Trace: {trace}

400 Bad Request

This errors happens if one ore more headers are invalid.

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

403 Forbidden

This error happens if at least one of the given URLs is not authorized.

See the Webhook module configuration for more details.

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

Callback Request

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

info

You may customize the Content-Disposition header thanks to output filename header.

Callback Error Request

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

{
    "status": "{status}",
    "message": "{message}"
}