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.