Redirects & Callbacks

Once a Task is created and is live, handling Worker entrances and redirecting them back to WXET is the primary concern. Determining where a Worker goes when they enter a Task is entirely determined by the live_url attribute. This formatted string is a url that get's substituted with a range of possible variables. These are available to the Survey or Task platform to use for their own purposes. The only required variable on live_url is the session_uuid because it is a required query parameter when redirecting the Worker back to WXET.

Worker Entering the Task

When WXET's Supplier Network determines to send a Worker into the Task, the Worker will enter the Task's live_url with an HTTP Redirect from the WXET platform. Every live_url must have a {{session_uuid}} and the Survey or Ephemeral Task platform must store that identifier. When a live_url is set, it must look something like:

https://enter.survey.com/?foo=1234&abc={{session_uuid}}

and when the Worker actually enters the Task, they'll be redirected to a URL that looks something like:

https://enter.survey.com/?foo=1234&abc=fb39dcedaeaf4e37887c1134ba98c743

Using this string replacement pattern allows WXET Accounts to construct URLs to match the requirements of your Survey or Task platform. In total, the following variables are all support for passing into a Task.

session_uuid (required): The unique identifier for the session.
task_uuid: The unique identifier for the task.
project_uuid: The unique identifier for the project.
account_uuid: The unique identifier for the account.
respondent_uuid: The unique identifier for the respondent.
cpi: If a dynamic pricing strategy is used, this is the selected price.

A formatted variable can also be a URL Path into a Survey or Task platform, so the following url https://enter.survey.com/task/{{project_uuid}}/{{session_uuid}}/ will correctly format to enter into the task like: https://enter.survey.com/task/b29c64b940c7488589ae532bb51bbbc2/e4293c79ac3a442b860cfd66bfb485bf/

Worker finished their Task Attempt

Regardless of the outcome, a WXET Account must issue a POST to the Set Wall Status endpoint before redirecting the Worker back into the WXET platform. This is

curl -X POST --location "https://api.wxet.org/v2/wall/<session_uuid>/status/" \
    -H "Authorization: <API-Token>"
    -H "Content-Type: application/json" \
    -d '{
          # "status": WXETStatus.COMPLETE.value,
          # "status_code_1": WXETStatusCode1.COMPLETE.value,
          "status": "c" 
          "status_code_1": 99
        }'

In the example above, I used the literal values for the cURL. However, you can see below the Enum definitions for WXETStatus and WXETStatusCode1

class WXETStatus(str, Enum, metaclass=ReprEnumMeta):
    # Worker completed the task and paid.
    COMPLETE = "c"

    # Worker did not complete task. They were rejected by either WXET or buyer.
    FAIL = "f"

    # Worker abandoned the task. Only set if the Buyer informs us that the
    # user took  some action to exit out of the task
    ABANDON = "a"

    # Worker either abandoned the task or was never returned. After a
    #   pre-determined amount of time (configurable), any task that does
    #   not have a status will time out.
    TIMEOUT = "t"

class WXETStatusCode1(int, Enum, metaclass=ReprEnumMeta):
    # This should only be NULL if the Status is ABANDON or TIMEOUT

    # The status code is not documented
    UNKNOWN = 1
    
    # Worker failed to be sent into a task.
    WXET_FAIL = 2
    
    # The worker abandoned/timed out within wxet before being sent to task
    WXET_ABANDON = 3
    
    # Buyer is explicitly blocked by the marketplace.
    WXET_BUYER_BLOCKED = 4
    
    # Worker rejected by buyer for over quota
    BUYER_OVER_QUOTA = 11  # Worker rejected by buyer for duplicate entrance
    
    # Worker unable to enter task due it not being available.
    BUYER_TASK_NOT_AVAILABLE = 12
    
    # Worker abandoned/timed out within the task
    BUYER_ABANDON = 13
    
    # Worker terminated in buyer task
    BUYER_FAIL = 14
    
    # Worker terminated in buyer task due to quality reasons
    BUYER_QUALITY_FAIL = 15
    
    # Worker redirect with no callback received
    BUYER_POSTBACK_NOT_RECEIVED = 30
    
    # Completed the Task
    COMPLETE = 99

Once this POST has been issued, a Worker can be HTTP 302 Redirected into the following URL: https://api.wxet.org/v2/wall/return/?session_uuid=<session_uuid> and WXET will ensure they are returned back to their respective WXET Supplier Network partner.

Last modified: 01 October 2024