Callbacks

On your tasks, you can optionally supply a callback_url, a fully qualified URL that we will POST with the results of the task when completed. The data will be served as a JSON body (application/json). Alternately, you can set a default callback URL in your profile, which will be used for tasks that do not specify one.

Additionally, in order to simplify testing and add support for email automation pipelines, you may provide an email address as the callback_url. In this case, each completed task will result in an email sent from [email protected] with the body as the task's JSON payload.

You should respond to the POST request with a 2xx status code. If we do not receive a 2xx status code, we will continue to retry up to 20 times over the course of the next 24 hours.

If we receive a 2xx status code, the task will be populated with a true value for the callback_succeeded parameter. Otherwise, if we do not receive a 2xx status code on any retry, the task will be populated with a false value for the callback_succeeded parameter.

Example callback body

{
  "task": {
    "task_id": "576c41bf13e36b0600b02b34",
    "completed_at": "2016-06-23T21:54:44.904Z",
    "response": {
      "category": "red"
    },
    "created_at": "2016-06-23T20:08:31.573Z",
    "callback_url": "http://www.example.com/callback",
    "type": "categorization",
    "status": "completed",
    "instruction": "Is this object red or blue?",
    "params": {
      "attachment_type": "text",
      "attachment": "tomato",
      "categories": [
        "red",
        "blue"
      ]
    },
    "metadata": {}
  },
  "response": {
    "category": "red"
  },
  "task_id": "576c41bf13e36b0600b02b34"
}

Getting Started

If you're just testing and want to try a few requests, the easiest way to get started is to use a RequestBin and send requests using the provided URL as the callback_url. You can also use ngrok to expose a local server to the internet for fast prototyping.

We've also found Pipedream to be an easy-to-use platform to receive webhooks, view logs, take other actions.

Authentication

If you'd like to authenticate our callbacks, we set a scale-callback-auth HTTP header on each of our callbacks. The value will be equal to your Live Callback Auth Key shown on your dashboard. If this header is not set, or it is set incorrectly, the callback is not from Scale.

Events that trigger a Callback

Callbacks are sent for the following events:

Error on Task Creation (see Errors for more details)
Task Completion
Audit Status Changes (Approved, Rejected, Fixed)
Tasks that are "Recalled" by Scale, meaning an operation on Scale's side converts completed tasks back to pending so they can have follow-on work done on them. This conversion is coordinated and communicated with you as the customer if it needs to happen.

POST Data

Property	Type	Description
task_id	string	The `task_id` is the unique identifier for the task. It is identical to `task.task_id`
status	string	The status of the task when it was completed. Normally `completed`, but can also be `error` in the case that a task failed to process. It is identical to `task.status`
response	object	The response object of the completed request. It is identical to task.response
task	object	The full Task Object for reference and convenience.

Re-sending a Callback

This endpoint re-sends a callback for a completed or errored task to the callback_url.If your callback server had gone down, or otherwise missed receiving a task, this endpoint will tell Scale to resend the callback's original data (above) to your server.

Request

POST/v1/task/{taskId}/send-callback

INSTALLATION
$ python -m pip install requests
---
import requests

url = "https://api.scale.com/v1/task/taskId/send-callback"

headers = {"accept": "application/json"}

response = requests.post(url, headers=headers)

print(response.text)