Polling and Postbacks

Blitline runs your jobs asynchronously, which means that after you submit your job, there will be a variable amount to time before your job has completed.

There are 3 ways for you to know that your job has completed: Postbacks, polling, and AWS Event Bridge

  • Postbacks: When the Blitline cloud machine calls your server back with JSON, thus notifying you that you job has completed.
  • Polling: When you ask Blitline, "is it done yet?"
  • AWS Event Bridge: Blitline can send you an Event Bridge event which you can hook up to a Lambda function or other AWS features. (Requires AWS)

Whether you are polling or using postbacks, you will get some JSON representing the results of the job processing

The JSON returned will always have a results as the root node. Under results will be the following nodes:

Successfull Result

  • images - An array of image nodes
    • image_identifier - Your identifier you submitted in your JSON
    • destination_url (such as s3_url or azure_url)
    • meta - field identifying metadata about the result image
      • height
      • width
  • job_id - The unique ID associated with this particular job.
  • original_meta - Metadata about the original “src” image.
    • height of original
    • width of original.
    "results": {
        "original_meta": {
            "width": 421,
            "height": 163
        "images": [
                "image_identifier": "MY_CLIENT_ID",
                "s3_url": "http://s3.amazonaws.com/blitline/2014061200/20/6_wj-2i_hZRZ7KJj-jwcndQ.jpg",
                "meta": {
                    "width": 421,
                    "height": 163
        "job_id": "2m-Ir2YMXQ3yec0NV476xag"

Error Result

Same as successful results with two addition nodes

  • errors - In the event of an error during processing, this node will contain an array of Strings containing the error messages.
  • failed_image_identifiers - In the event of an error, this node will contain an array of image_identifiers that did NOT get processed.
    "results": {
        "original_meta": {},
        "images": [],
        "job_id": "4weK03Kd0j-D_ttohR7GTcg",
        "errors": [
            "Image processing failed. Unknown function named 'blu3r'"
        "failed_image_identifiers": [

How do I get a Postback?

Postbacks are the recommended way to use Blitline. Postbacks scale as large as you want to scale. Need a million postbacks per hour, no problem.

You can specify your postback location by adding a postback_url to your job JSON. This url will be called as soon as the job has completed.

How do I Poll?

Polling is great for development, and sometimes necessary in certain use cases.

Polling has rate limits though. You will not be able to poll for 8 million job_ids. In fact the current limit is 5 per second per application ID.

Show me how

How do I use AWS Event Bridge?

Check out our Event Bridge setup page here:

​Event Bridge

Is there useful tools for debugging Postbacks?

YES! We highly recommend https://requestbin.com . This allows you to make a free http destination url, which you can use for your postback_url

This allows you to easily inspect what Blitline is posting back to your client before you even build the client.