Webhook

The Webhook module provides a middleware that allows you to upload the output file from multipart/form-data routes to the destination of your choice.

Properties

Security

--webhook-allow-list       string  Set the allowed URLs for the webhook feature using a regular expression
--webhook-deny-list        string  Set the denied URLs for the webhook feature using a regular expression
--webhook-error-allow-list string  Set the allowed URLs in case of an error for the webhook feature using a regular expression
--webhook-error-deny-list  string  Set the denied URLs in case of an error for the webhook feature using a regular expression

Retry

--webhook-max-retry       int       Set the maximum number of retries for the webhook feature (default 4)
--webhook-retry-min-wait  duration  Set the minimum duration to wait before trying to call the webhook again (default 1s)
--webhook-retry-max-wait  duration  Set the maximum duration to wait before trying to call the webhook again (default 30s)

Timeout

--webhook-client-timeout  duration  Set the time limit for requests to the webhook (default 30s)

Disable

--webhook-disable bool  Disable the webhook feature

caution

--api-webhook-* properties are deprecated.

Middleware

The middleware reads the following headers:

• 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 - default POST).
• Gotenberg-Webhook-Error-Method - the HTTP method to use if error (POST, PATCH, or PUT - default POST).
• Gotenberg-Webhook-Extra-Http-Headers - the extra HTTP headers to send to both URLs (JSON format).

For instance:

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

Response

Status: 204 No Content

Error (headers validation)

Status: {status}

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

Body: {error}

Callback Request

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

Body: {output-file}

tip

You may customize the Content-Disposition header thanks to Output Filename middleware.

Callback Error Request

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

Body:

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

tip

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