---
title: Webhooks FAQ
subtitle: How Skyvern notifies you when its done
slug: running-tasks/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](api-reference/api-reference/agent/run-task#request.body.webhook_url) to receive the update when the task is done.
- Set [webhook_url in Run Workflow](https://docs.skyvern.com/api-reference/api-reference/agent/run-workflow#request.body.webhook_url) to receive the update when a workflow run is done.

To fetch the status of a run:
- Use the [Get Run](/api-reference/api-reference/agent/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:
```json
{
   "run_id": "The ID of the task or the workflow run. For examples: tsk_123, tsk_v2_123, wr_123",
   "run_type": "The type of the run. Examples: task_v1, task_v2, workflow_run, openai_cua, anthropic_cua.",
   "status": "The status of the run",
   "output": "The output of the run",
   "downloaded_files": "A list of download file objects",
   "recording_url": "The URL of the recording",
   "screenshot_urls": "URLs of the last three screenshots. The first one in the list is the latest screenshot.",
   "failure_reason": "The reason for the failure if any",
   "app_url": "The URL to the run in the Skyvern app",
   "created_at": "The timestamp when the run was created",
   "modified_at": "The timestamp when the run was last modified",
}
```
For detailed schema, please refer to the [Run Response](/api-reference/api-reference/agent/get-run#response).

Notes:
- The webhook payload won't contain the `run_request` field as the [Run Response](/api-reference/api-reference/agent/get-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?)

<CodeGroup>
```python Python
import hmac
from fastapi import Request

def validate_skyvern_request_headers(request: Request) -> bool:
    header_skyvern_signature = request.headers["x-skyvern-signature"]
    payload = request.body() # this is a bytes
    hash_obj = hmac.new(SKYVERN_API_KEY.encode("utf-8"), msg=payload, digestmod=hashlib.sha256)
    client_generated_signature = hash_obj.hexdigest()
    return header_skyvern_signature == client_generated_signature
```

```javascript Javascript
const crypto = require('crypto');

function validateSkyvernRequestHeaders(req) {
    const headerSkyvernSignature = req.headers['x-skyvern-signature'];
    const payload = req.body; // assuming req.body is a Buffer or string
    const hash = crypto.createHmac('sha256', process.env.SKYVERN_API_KEY)
                        .update(payload)
                        .digest('hex');
    return headerSkyvernSignature === hash;
}
```

</CodeGroup>

## Can I Replay Webhook?

Yes, you can replay a webhook by using the [Retry Webhook](/api-reference/api-reference/agent/retry-webhook) endpoint.