A full async workflow #

Doppio has the ability to respond immediatly to your request and send you the rendered document once it is done. This can help you save resources as a rendering can easily take a few seconds to complete depending on the content.

How does it work ? #

An async request goes as follows:

• Step ❶: You call our API on an async route.

• Step ❷: Doppio examines the content of your request. If everything checks out (authorization passed, request limits passed, payload validated), it responds immediately with a 200 OK status and add your request into a queue. If not, it responds with the appropriate error code and message to let you know what's wrong.

• Step ❸: Doppio renders your document while your app can go on with its work.

• Step ❹: Doppio calls the route you provided in the request payload (called a webhook) to send you the result of the render.

How to use it ? #

1. Firstly, implement a route on your side which will handle our webhook call. This route will receive a payload with informations on your render process:

{
  "doppioRequestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", // Request ID: to link our webhook request to your async render request. The same id will be given to you in the response to your request
  "renderStatus": "SUCCESS", // Status of the render. Could be "SUCCESS" if successfull or "ERROR" if not
  "documentUrl": "string", // URL which hosts the document
  "isAsync": true, // is an async request
  "isCustomBucket": true // if the S3 bucket used to host the document is your own.
}

This route will also receive some specific headers:

• x-doppio-request-id: same requestId as mentionned in the webhook requet payload and your request response.
• x-doppio-payload-signature: signature of the request. Please verify it to ensure the authenticity and integrity of our request. See here for more info on how to do this.

2. Secondly, add your webhook handler route configuration to your async request. It is expected on the payload doppio property:

{
    "doppio": {
        "webhook": {
            "url": "<YOUR_WEBHOOK_HANDLER_URL>", // URL of the webhook handler
            "method": "POST", // HTTP verb to use in the request. Usually POST or PUT
            "headers": {} // optionnal headers to add to the request
        }
    },
    "page": { ... }
    ...
}

3. Finally, handle the response body of your request in order to find the webhook call associated with your request.

{
    "requestId": "<YOUR_REQUEST_ID>", // Format doppioreq_<uuid>. Save it to find the following webhook call
    "jobId": "<RENDERING_JOB_ID>" // Save it in case of a problem
}

Save the requestId somewhere so you can find the rendered document in the following webhook call. Also save the jobId juste in case. If anything goes wrong, contact us with this jobId so we can track your request in our rendering and webhook queues and investigate what happened.