Tasks

Webhooks FAQ

How Skyvern notifies you when its done

Webhooks vs HTTP requests?

Task runtimes can exceed default HTTP timeouts; we recommend using webhook notifications to inform you when the run is complete.

To set up webhook callback:

To fetch the status of a run:

  • Use the Get Run endpoint for the status of a task or workflow run

Webhook payload schema

The webhook request body is a JSON object with the following fields:

1{
2   "run_id": "The ID of the task or the workflow run. For examples: tsk_123, tsk_v2_123, wr_123",
3   "run_type": "The type of the run. Examples: task_v1, task_v2, workflow_run, openai_cua, anthropic_cua.",
4   "status": "The status of the run",
5   "output": "The output of the run",
6   "downloaded_files": "A list of download file objects",
7   "recording_url": "The URL of the recording",
8   "screenshot_urls": "URLs of the last three screenshots. The first one in the list is the latest screenshot.",
9   "failure_reason": "The reason for the failure if any",
10   "app_url": "The URL to the run in the Skyvern app",
11   "browser_session_id": "The ID of the browser session",
12   "max_screenshot_scrolls": "The maximum number of scrolls for the post action screenshot. When it's None or 0, it takes the current viewpoint screenshot",
13   "run_request": "The original request parameters used to start this task or workflow run",
14   "script_run": "The script run result containing information like whether AI fallback is triggered when the script fails",
15   "created_at": "The timestamp when the run was created",
16   "modified_at": "The timestamp when the run was last modified",
17   "queued_at": "The timestamp when the run was queued",
18   "started_at": "The timestamp when the run started",
19   "finished_at": "The timestamp when the run finished"
20}

For detailed schema, please refer to the Run Response.

Notes:

  • The webhook payload won’t contain the run_request field as the Run Response does.
  • There are legacy fields in the actual payload for backward compatibility, which are not listed here and will be removed in the future. Please use the fields above.

How do we handle webhook authentication? (ie how can we handle callbacks?)

1import hmac
2from fastapi import Request
3
4def validate_skyvern_request_headers(request: Request) -> bool:
5    header_skyvern_signature = request.headers["x-skyvern-signature"]
6    payload = request.body() # this is a bytes
7    hash_obj = hmac.new(SKYVERN_API_KEY.encode("utf-8"), msg=payload, digestmod=hashlib.sha256)
8    client_generated_signature = hash_obj.hexdigest()
9    return header_skyvern_signature == client_generated_signature

Can I Replay Webhook?

Yes, you can replay a webhook by using the Retry Webhook endpoint.