Webhook Run Info

Overview

By default, webhooks do not reveal any information to the request originator beyond whether Valohai has accepted the webhook.

This behaviour can be customized by returning the Trigger’s Run ID to the requester.

Adding the Run ID

You can return either plain text or JSON from the webhook. Run ID can be added to either type of response using the {run_id} placeholder.

For JSON, the placeholder must be inside a string within the JSON document. It can also be within nested objects.

Using the Run ID

The run info endpoint is a sub-endpoint of the webhook launch endpoint, located at https://app.valohai.com/api/v0/launch/<trigger_ID>/run/. Accessing it requires passing the same request authentication conditions as the original launch request.

With a GET request, add ?run_id=<run_id> as the query parameter. If your authentication conditions require additional query parameters, add them as well.

With a POST request, include a run_id value in the request body. The request body can be either form encoded or JSON. When using JSON remember to add a Content-Type: application/json header, and supply run_id in the top level object. Using POST is required to comply with HMAC authentication conditions that validate the request body.

The run info endpoint returns information about the trigger run’s status and action results.

The run may be pending:

{
    "status": "pending",
    "result": []
}

This indicates the trigger run is being processed by Valohai, and you should request run info again later.

When the run has completed, action results are also included:

{
    "status": "completed",
    "result": [
        {
            "action": "run_execution",
            "execution_step": "Batch feature extraction",
            "execution_id": "<the created execution ID>"
        }
    ]
}

Actions that run pipelines, copy pipelines and run executions will declare the objects they create using this API.

Error details during trigger run are not reported using this API, but the status will be error (all actions failed) or complete_with_error (some actions were successful). You can find error details in the trigger log.