Sending Notifications to Downstream Servers

priint:cloud can send two types of notification to downstream servers (like PIM system or Data Agent):

• callback notification is sent on rendering success
• error notification is sent on any failure during ticket processing that cannot be "healed" by re-delivery.

Callback by priint-cloud

Callback is triggered on successful rendering and very similar to the upload except that it does not contain the binary data of the PDF. It typically contains the download URI as a string.

To activate callbacks the REST API must be configured to execute a webhook on rendering success.

/restapi/config.ion - Example configuration for callback webhook

{
  "callback": "https://example.com/priint/v1/success/{foreignKey}"
}

As with a "callback" for the URI pattern defined in the /restapi/config.ion you will need a connection entry in the /callback/config.ion.

You will probably use one or both of default parameter fields to build your payload value pattern.

The following parameters can be used in payloads or URI patterns:

Name	Description
location	The absolute download URI for the PDF using the storage endpoint of the REST API
tenant	Name of the priint:cloud tenant
project	Name of the priint:cloud project
user	The authenticated user
ticket	priint:cloud ticket id useful to refer to a rendering
foreignKey	Only set if defined in original /renderpdf called that triggered the job.
dateTime	ISO DateTime string for the rendering
timestamp	Milliseconds since 1970 for the rendering
<custom>	Any custom variable set in the original /renderpdf call.

Example: Define payload for webhook notification on success

/callback/config.ion - Example connection configuration for callback webhook

{
  "connections": [
    {
      "method": "POST",
      "url": "https://example.com/priint/v1/callback/",
      "authentication": {
        "type": "ApiKey",
        "key": "API-KEY",
        "value": "7271d91c0d8e104bcc93c9f7af5626bbfae2c0295eced7d86985b90f639e8844"
      },
      "header": {
        "content-type": "application/x-www-form-urlencoded"
      },
      "payload": [
        {
          "value": "downloadUrl={location}&ticket={ticket}"
        }
      ]
    }
  ]
}

If the endpoint responds with success (HTTP 2xx) than the rendering service regards the job as completed and will per default remove all files related to that job from the object store. In case the endpoint fails the request will re-attempted once after a short delay The details of this behavior can be overridden by configuration.

The request would look like this:

Example http request for callback webhook

POST /priint/v1/callback/bd6c313f5094d2a45834eb4d92c2caa7 
Host: example.com
Authorization: Basic c3VlZG9lOjkzNTlkODNjYzY2Yzc4ZTYxZWI1ZjEzZTRiNmE5MWY1MDcxZGI3MTI
Content-Type: application/x-www-form-urlencoded

downloadUrl=https%3A%2F%2Fapi.priintcoud.com%2Frest%2Ftenants%2Fexample.com%2Fprojects%2Fmy-first-datasheet%2Fstorage%2F76wirw7rwei842.pdf&ticket=76wirw7rwei842

The priint:cloud location parameter is used as request parameter named "downloadUrl". In the example it computes to "https://api.priintcoud.com/rest/tenants/example.com/projects/my-first-datasheet/storage/76wirw7rwei842.pdf".

Using GET instead of POST

Callback is using HTTP POST by default (webhook standard), but can also be configured to use simple GET requests. Normally, this is not recommended for security reasons. But if your content system does only support GET here is an example how to configure it:

/callback/config.ion - Example connection configuration for callback webhook using GET

{
  "connections": [
    {
      "method": "GET",
      "url": "https://example.com/priint/v1/callback/",
      "authentication": {
        "type": "ApiKey",
        "key": "API-KEY",
        "value": "7271d91c0d8e104bcc93c9f7af5626bbfae2c0295eced7d86985b90f639e8844"
      }
    }
  ]
}

Error Notification by priint-cloud

The rendering service will send a notification to a webhook URL when a rendering finally fails sometime after the original job creation. The webhook URL can be defined in /restapi/config.ion.

We say finally fails to make clear that renderings are typically re-tried once or twice with some configurable delay in between the attempts. The rendering service expects that single renderings may fail due to temporary reason like short timed network instabilities etc.

The configuration of the error notification is essentially same as for "callback".

To activate error notifications restapi must be configured to execute a webhook on rendering failures like this:

/restapi/config.ion - Example configuration for error webhook

{
  "error": "https://example.com/priint/v1/error"
}

The connection config path is /error/config.ion.

The following parameters can be used in payloads or URI patterns:

Name	Description
errorMessage	Textual error message
tenant	Name of the priint:cloud tenant
project	Name of the priint:cloud project
user	The authenticated user
ticket	internal job id
foreignKey	Only set if defined in original /renderpdf called that triggered the job.
dateTime	ISO DateTime string for the rendering
timestamp	Milliseconds since 1970 for the rendering
<custom>	Any custom variable set in the original /renderpdf call.