Webhook

The webhook feature enables Gotenberg to upload the output file originating from multipart/form-data routes to a selected destination. Upon employing the webhook feature, the API promptly returns a 204 No Content response, and the entire process is carried out asynchronously.

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

Content-Type: text/plain; charset=UTF-8
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 when the one of given URLs is not authorized.

See the Webhook module configuration for more details.

Content-Type: text/plain; charset=UTF-8
Gotenberg-Trace: {trace}
Body: Invalid '{header_key}' header value: '{url}' does not match the authorized URLs

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}"
}