Webhooks FAQ

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:

• Set webhook_url in Run Task to receive the update when the task is done.
• Set webhook_url in Run Workflow to receive the update when a workflow run is done.

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
   "created_at": "The timestamp when the run was created",
12
   "modified_at": "The timestamp when the run was last modified",
13
}

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?)

1
import hmac
2
from fastapi import Request
3
4
def 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.