Webhooks

Instead of waiting for an Assembly to finish and its API request to respond, you can also configure a Webhook, also known as an Assembly Notification. The system will send a POST request to a URL of your choosing containing a full report once an Assembly ends.

Why use Webhooks?

By choosing to use Webhooks you enable your end-users to have a smoother experience, as they only need to wait for file uploads to finish before they can close the browser window. Without file uploads, they could even close the browser window right away.

How to activate Webhooks?

You activate webhooks by adding notify_url to your Assembly instructions in your Template on the same JSON level as steps:

{
  "steps": { ... },
  "notify_url": "https://example.com/transloadit_pingback"
}

When you then run your Template Transloadit is going to inform your back-end once all processing has happened by sending a POST request to that defined URL containing all the Assembly status json.

If you don't want your users/program to wait for encoding, this often also involves setting a flag. In the case of Uppy, set the waitForEncoding parameter to false. In many back-end SDKs, waiting for encoding involves explicitly polling the Assembly Status, so just refraining from that will do the trick.

Your back-end needs to respond with a 200 header, otherwise Transloadit assumes the Notification has failed and retries it a few times with exponential backoff.

What does this POST request look like?

This multipart POST request contains a field called transloadit, which contains the full Assembly Status JSON. You can find an example of this in our API Response docs. It will also contain a signature field so that you could optionally verify that the request indeed came from us and was not tampered with. How to calculate that signature with your Auth Secret to match the one we sent is shown in the code example below.

Code Example

Let's assume you had indeed specified "notify_url": "https://example.com/transloadit_pingback" and that the back-end server that would accept incoming POSTs there was written in Node.js. That could look like this:

You could run this script like so:

$ env AUTH_SECRET=******** node notification-backend-node.js 3020
Server started, listening on http://0.0.0.0:3020

Trying the Code Example locally

While you're testing locally behind a NAT, you could use a tool like ngrok so Transloadit can still reach your local script. Ngrok is a paid service, but limited use is free forever, and sufficient for our testing purposes. In a new tab:

$ brew cask install ngrok || snap install ngrok # || https://ngrok.com/download
ngrok 2.3.35 from Khiem Doan (khiemdoan) installed

$ ngrok http 3020
Forwarding                    http://2cf99440.ngrok.io -> http://localhost:3020

You can now create a Template and paste the following Instructions. Don't forget to replace the ngrok code of 2cf99440 to whatever ngrok reported in your case:

{
  "notify_url": "http://2cf99440.ngrok.io/transloadit_pingback",
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "faces_detected": {
      "use": ":original",
      "robot": "/image/facedetect",
      "crop": true,
      "faces": "max-confidence",
      "crop_padding": "10%",
      "format": "preserve"
    }
  }
}

Note: At the time of writing ngrok appears to have issues with AWS ranges. If this is the case for you, an alternative to try is localtunnel.

Now you're ready to test right inside the browser. The Instructions we used detect a face, so for optimal results, upload a photo of someone using the Template Editor's testing area. You can use Uppy's Webcam feature if you don't have a picture available.

Your Node.js script should report it has successfully received the Assembly Notification when the Assembly completes:

-- > ASSEMBLY_COMPLETED https://api2.transloadit.com/assemblies/b2b580bdc969427091a48f1f0d3d9d40
^- uploaded 'avatar.jpg' ready at https://s3.amazonaws.com/tmp.transloadit.com/ff89be82...
^- faces_detected 'avatar.jpg' ready at https://s3.amazonaws.com/tmp.transloadit.com/fd2f61b9...

In addition, you'll see a record of the notification on the Assembly page, where you can also manually retry it for further testing.

The Example code higher up shows how to calculate signatures in Node.js. There are examples for many other languages in the Signature Authentication docs.