Automate browser based workflows with AI
Python aiapiautomationbrowserbrowser-automationcomputergptllmplaywrightpowerautomatepuppeteerpythonrpaseleniumvisionworkflow
fix(SKY-13101): documented webhook verifier now rejects forged signatures (#7987)
Aaron Perezdd2b6bb9aa35
diff --git a/docs/cloud/managing-credentials/totp-setup.mdx b/docs/cloud/managing-credentials/totp-setup.mdxindex c5954faae..59de767d3 100644--- a/docs/cloud/managing-credentials/totp-setup.mdx+++ b/docs/cloud/managing-credentials/totp-setup.mdx@@ -13,6 +13,8 @@ keywords:- verification---+import WebhookSignatureVerification from "/snippets/webhook-signature-verification.mdx";+Skyvern supports three 2FA methods for automated logins. **Authenticator App (TOTP)** is fully automatic: Skyvern generates codes locally. **Email** and **Text Message** require you to push codes via the UI or API. All three are configured on the [password credential](/cloud/managing-credentials/password-credentials) itself.## Authenticator App (TOTP)@@ -187,21 +189,7 @@ Your endpoint must accept a POST request with `task_id`, `workflow_run_id`, and}```-Validate the `x-skyvern-signature` header to confirm the request came from Skyvern:--```python-import hashlib, hmac--def validate_skyvern_request(request) -> bool:- signature = request.headers["x-skyvern-signature"]- payload = request.body() # bytes- expected = hmac.new(- SKYVERN_API_KEY.encode("utf-8"),- msg=payload,- digestmod=hashlib.sha256,- ).hexdigest()- return signature == expected-```+<WebhookSignatureVerification />---diff --git a/docs/developers/credentials/handle-2fa.mdx b/docs/developers/credentials/handle-2fa.mdxindex 36d278de3..bfcb8a831 100644--- a/docs/developers/credentials/handle-2fa.mdx+++ b/docs/developers/credentials/handle-2fa.mdx@@ -16,6 +16,8 @@ keywords:- verification---+import WebhookSignatureVerification from "/snippets/webhook-signature-verification.mdx";+Many websites require two-factor authentication (2FA) during login. Skyvern supports multiple 2FA methods to handle these flows automatically.---@@ -344,24 +346,7 @@ Content-Type: application/json### Step 2: Verify request signatures-Skyvern signs all requests using HMAC-SHA256 with your API key. Verify the signature to ensure requests are authentic:--```python-import hmac-import hashlib--def verify_skyvern_request(request, api_key: str) -> bool:- signature = request.headers.get("x-skyvern-signature")- payload = request.body # bytes-- expected = hmac.new(- api_key.encode("utf-8"),- msg=payload,- digestmod=hashlib.sha256- ).hexdigest()-- return hmac.compare_digest(signature, expected)-```+<WebhookSignatureVerification />### Step 3: Configure the login or blockdiff --git a/docs/developers/going-to-production/webhooks.mdx b/docs/developers/going-to-production/webhooks.mdxindex d64024a15..09be7f961 100644--- a/docs/developers/going-to-production/webhooks.mdx+++ b/docs/developers/going-to-production/webhooks.mdx@@ -14,6 +14,8 @@ keywords:- failure handling---+import WebhookSignatureVerification from "/snippets/webhook-signature-verification.mdx";+Agents and task runs are asynchronous. When you call `run_task` or `run_workflow`, the API returns immediately with a run ID, but the actual execution happens in the background and can take variable time.Instead of polling the `get_runs` endpoint, you can use Webhooks to get notified when they finish. Webhooks fire only when a run reaches a terminal status: `completed`, `failed`, `terminated`, `timed_out`, or `canceled`.@@ -259,119 +261,7 @@ User-Agent: python-httpx/0.28.1## Optional: Verify webhook signatures-Skyvern signs every webhook with your API key using HMAC-SHA256, so you can verify the request actually came from Skyvern before acting on it.--**Headers sent with every webhook:**-- `x-skyvern-signature`: HMAC-SHA256 signature of the payload-- `x-skyvern-timestamp`: Unix timestamp when the webhook was sent-- `Content-Type: application/json`--<CodeGroup>-```python Python-import hmac-import hashlib-from fastapi import Request, HTTPException--async def handle_webhook(request: Request):- signature = request.headers.get("x-skyvern-signature")- payload = await request.body()-- expected = hmac.new(- SKYVERN_API_KEY.encode("utf-8"),- msg=payload,- digestmod=hashlib.sha256- ).hexdigest()-- if not hmac.compare_digest(signature, expected):- raise HTTPException(status_code=401, detail="Invalid signature")-- data = await request.json()- # Process the webhook...-```--```typescript TypeScript-import crypto from "crypto";-import express from "express";--app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {- const signature = req.headers["x-skyvern-signature"];- const payload = req.body;-- const expected = crypto- .createHmac("sha256", process.env.SKYVERN_API_KEY)- .update(payload)- .digest("hex");-- // Use timing-safe comparison to prevent timing attacks- let valid = false;- try {- crypto.timingSafeEqual(- Buffer.from(signature || ''),- Buffer.from(expected)- );- valid = true;- } catch (err) {- valid = false;- }-- if (!valid) {- return res.status(401).send("Invalid signature");- }-- const data = JSON.parse(payload);- // Process the webhook...- res.status(200).send("OK");-});-```--```go Go-package main--import (- "crypto/hmac"- "crypto/sha256"- "encoding/hex"- "io"- "net/http"- "os"-)--func webhookHandler(w http.ResponseWriter, r *http.Request) {- signature := r.Header.Get("x-skyvern-signature")- payload, err := io.ReadAll(r.Body)- if err != nil {- http.Error(w, "Failed to read request body", http.StatusBadRequest)- return- }-- mac := hmac.New(sha256.New, []byte(os.Getenv("SKYVERN_API_KEY")))- mac.Write(payload)- expected := hex.EncodeToString(mac.Sum(nil))-- if !hmac.Equal([]byte(signature), []byte(expected)) {- http.Error(w, "Invalid signature", http.StatusUnauthorized)- return- }-- // Process the webhook...- w.WriteHeader(http.StatusOK)-}-```-</CodeGroup>---<Note>-**Use constant-time comparison** to prevent timing attacks:-- Python: `hmac.compare_digest()`-- TypeScript: `crypto.timingSafeEqual()`-- Go: `hmac.Equal()`--Never use simple equality operators (`==` or `===`) for signature comparison as they are vulnerable to timing attacks.-</Note>--<Warning>-**Always validate against the raw request body bytes.** Skyvern normalizes JSON before signing: it removes whitespace (using compact separators) and converts whole-number floats to integers (`3.0` becomes `3`). If you parse the JSON and re-serialize it, the byte representation will differ and signature validation will fail.-</Warning>+<WebhookSignatureVerification />---diff --git a/docs/snippets/webhook-signature-verification.mdx b/docs/snippets/webhook-signature-verification.mdxnew file mode 100644index 000000000..bcd0d3ea3--- /dev/null+++ b/docs/snippets/webhook-signature-verification.mdx@@ -0,0 +1,145 @@+Skyvern signs every webhook and TOTP request with your API key using HMAC-SHA256, so you can verify the request actually came from Skyvern before acting on it.++**Headers sent with every request:**+- `x-skyvern-signature`: HMAC-SHA256 signature of the payload, hex-encoded+- `x-skyvern-timestamp`: Unix timestamp when the request was sent+- `Content-Type: application/json`++Copy the verifier for your language and reject the request whenever it returns false.++<Warning>+**If you copied a verifier from this page before August 2026, re-check it.** Earlier versions+of these examples were permissive: the TypeScript example called `crypto.timingSafeEqual()`+without using its return value, so any signature of the right length was accepted, and the+TOTP examples compared signatures with `==`. Replace them with the verifiers below.+</Warning>++<CodeGroup>+```python Python+import hashlib+import hmac+import os++from fastapi import HTTPException, Request++SKYVERN_API_KEY = os.environ["SKYVERN_API_KEY"]+++def verify_skyvern_signature(raw_body: bytes, signature: str | None) -> bool:+ if not signature:+ return False+ expected = hmac.new(+ SKYVERN_API_KEY.encode("utf-8"),+ msg=raw_body,+ digestmod=hashlib.sha256,+ ).hexdigest()+ # Compared as bytes: compare_digest raises TypeError on a non-ASCII str,+ # and the signature header is attacker-controlled.+ return hmac.compare_digest(signature.encode("utf-8"), expected.encode("utf-8"))+++async def handle_webhook(request: Request):+ raw_body = await request.body()+ signature = request.headers.get("x-skyvern-signature")++ if not verify_skyvern_signature(raw_body, signature):+ raise HTTPException(status_code=401, detail="Invalid signature")++ data = await request.json()+ # Process the request...+```++```typescript TypeScript+import crypto from "crypto";+import express from "express";++function verifySkyvernSignature(rawBody: Buffer, signature: unknown): boolean {+ if (typeof signature !== "string" || signature.length === 0) {+ return false;+ }+ const apiKey = process.env.SKYVERN_API_KEY;+ if (!apiKey) {+ throw new Error("SKYVERN_API_KEY is not set");+ }+ const expected = crypto.createHmac("sha256", apiKey).update(rawBody).digest("hex");+ const received = Buffer.from(signature, "utf8");+ const digest = Buffer.from(expected, "utf8");+ // timingSafeEqual throws unless both buffers are the same length, so compare+ // lengths first and return its result -- never discard it.+ return received.length === digest.length && crypto.timingSafeEqual(received, digest);+}++app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {+ if (!verifySkyvernSignature(req.body, req.headers["x-skyvern-signature"])) {+ return res.status(401).send("Invalid signature");+ }++ const data = JSON.parse(req.body);+ // Process the request...+ res.status(200).send("OK");+});+```++```go Go+package main++import (+ "crypto/hmac"+ "crypto/sha256"+ "encoding/hex"+ "io"+ "net/http"+ "os"+)++func verifySkyvernSignature(rawBody []byte, signature string) bool {+ apiKey := os.Getenv("SKYVERN_API_KEY")+ // Without this, an unset key would sign with "" -- a key an attacker also knows.+ if signature == "" || apiKey == "" {+ return false+ }+ mac := hmac.New(sha256.New, []byte(apiKey))+ mac.Write(rawBody)+ expected := hex.EncodeToString(mac.Sum(nil))+ return hmac.Equal([]byte(signature), []byte(expected))+}++func webhookHandler(w http.ResponseWriter, r *http.Request) {+ rawBody, err := io.ReadAll(r.Body)+ if err != nil {+ http.Error(w, "Failed to read request body", http.StatusBadRequest)+ return+ }++ if !verifySkyvernSignature(rawBody, r.Header.Get("x-skyvern-signature")) {+ http.Error(w, "Invalid signature", http.StatusUnauthorized)+ return+ }++ // Process the request...+ w.WriteHeader(http.StatusOK)+}+```+</CodeGroup>++<Warning>+**Act on the comparison result, and reject a missing signature.** A constant-time+comparison only protects you if you branch on what it returns. Two ways to get this+wrong: calling `crypto.timingSafeEqual()` for its side effects and treating "it did not+throw" as success — it only throws on a length mismatch, so every wrong-but-64-character+signature passes — or computing a verdict and never checking it. A request that arrives+with no `x-skyvern-signature` header at all must be rejected, not crash your handler.+</Warning>++<Note>+**Use constant-time comparison** to prevent timing attacks:+- Python: `hmac.compare_digest()`+- TypeScript: `crypto.timingSafeEqual()`+- Go: `hmac.Equal()`++Never use simple equality operators (`==` or `===`) for signature comparison as they are vulnerable to timing attacks.+</Note>++<Warning>+**Always validate against the raw request body bytes.** Skyvern normalizes JSON before signing: it removes whitespace (using compact separators) and converts whole-number floats to integers (`3.0` becomes `3`). If you parse the JSON and re-serialize it, the byte representation will differ and signature validation will fail.+</Warning>diff --git a/tests/unit/test_docs_webhook_verification_snippets.py b/tests/unit/test_docs_webhook_verification_snippets.pynew file mode 100644index 000000000..afd6fd31b--- /dev/null+++ b/tests/unit/test_docs_webhook_verification_snippets.py@@ -0,0 +1,232 @@+"""Executes the published webhook-signature verifiers against real Skyvern signatures.++The fixtures come from generate_skyvern_webhook_signature, the same function that signs+outbound webhooks and TOTP requests, so a snippet that passes here matches server behavior.+"""++import base64+import json+import os+import re+import shutil+import subprocess+import textwrap+from collections.abc import Callable+from pathlib import Path++import pytest++from skyvern.forge.sdk.core.security import generate_skyvern_webhook_signature++REPO_ROOT = Path(__file__).resolve().parents[2]+SNIPPET = REPO_ROOT / "docs/snippets/webhook-signature-verification.mdx"++API_KEY = "sk_docs_snippet_test_key"+PAYLOAD = {"run_id": "tsk_1", "status": "completed", "step_count": 3}+_SIGNED = generate_skyvern_webhook_signature(payload=PAYLOAD, api_key=API_KEY)+RAW_BODY = _SIGNED.signed_payload.encode("utf-8")+GENUINE = _SIGNED.headers["x-skyvern-signature"]++# What an attacker can produce unaided if a verifier signs with an unset key: the empty+# key is public, so this is a valid signature for anyone who guesses the key is missing.+EMPTY_KEY_FORGED = generate_skyvern_webhook_signature(payload=PAYLOAD, api_key="").headers["x-skyvern-signature"]++# (label, signature, must_be_accepted)+CASES = [+ ("genuine", GENUINE, True),+ ("forged_same_length", "a" * len(GENUINE), False),+ ("forged_off_by_one_char", "b" + GENUINE[1:], False),+ ("forged_with_empty_key", EMPTY_KEY_FORGED, False),+ ("empty", "", False),+ ("missing", None, False),+ ("non_ascii", "é" * len(GENUINE), False),+]++SPEC = json.dumps({"rawBody": base64.b64encode(RAW_BODY).decode(), "cases": [[c[0], c[1]] for c in CASES]})+++def _code_block(language: str) -> str:+ body = SNIPPET.read_text(encoding="utf-8")+ match = re.search(rf"^```{language}\b[^\n]*\n(.*?)^```$", body, re.M | re.S)+ assert match, f"no ```{language} block in {SNIPPET}"+ return match.group(1)+++def _extract(language: str, pattern: str) -> str:+ block = _code_block(language)+ match = re.search(pattern, block, re.M | re.S)+ assert match, f"no verifier function found in the {language} snippet"+ return match.group(0)+++def _assert_verdicts(verdicts: dict[str, bool]) -> None:+ for label, _signature, must_accept in CASES:+ assert label in verdicts, f"driver returned no verdict for {label}"+ assert verdicts[label] is must_accept, (+ f"documented verifier {'rejected the genuine' if must_accept else 'ACCEPTED a bad'} "+ f"signature for case {label!r}"+ )+++def test_python_snippet_rejects_forged_and_missing_signatures(monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv("SKYVERN_API_KEY", API_KEY)+ key_setup = _extract("python", r"^SKYVERN_API_KEY = [^\n]*$")+ source = _extract("python", r"^def verify_skyvern_signature\b.*?\n(?=^\S|\Z)")++ namespace: dict = {}+ exec(f"import hashlib\nimport hmac\nimport os\n\n{key_setup}\n\n{source}", namespace)+ verify = namespace["verify_skyvern_signature"]++ _assert_verdicts({label: verify(RAW_BODY, signature) for label, signature, _ in CASES})+++def _run_driver(cmd: list[str], workdir: Path, api_key: str | None = API_KEY) -> dict[str, bool] | None:+ """Returns the driver's verdicts, or None when it refused to run without a key."""+ env = {k: v for k, v in os.environ.items() if k != "SKYVERN_API_KEY"}+ if api_key is not None:+ env["SKYVERN_API_KEY"] = api_key++ result = subprocess.run(cmd, cwd=workdir, capture_output=True, text=True, timeout=120, env=env)+ if api_key is None and result.returncode != 0:+ return None+ assert result.returncode == 0, f"driver failed:\n{result.stdout}\n{result.stderr}"+ return json.loads(result.stdout.strip().splitlines()[-1])+++def _require_runtime(name: str) -> None:+ # Skipped rather than failed when absent: this file is synced to the OSS repo, whose+ # CI does not install either toolchain. test_docs_contain_no_permissive_signature_check+ # is pure Python and always runs, so both original defects stay covered regardless.+ if shutil.which(name) is None:+ pytest.skip(f"{name} not installed")+++def _typescript_driver(tmp_path: Path) -> list[str]:+ source = _extract("typescript", r"^function verifySkyvernSignature\b.*?^\}\n")+ # Node runs the snippet as plain JavaScript; drop the TypeScript-only annotations.+ # The substitution count is asserted so a changed signature fails loudly here.+ source, substitutions = re.subn(r"\(rawBody: Buffer, signature: unknown\): boolean", "(rawBody, signature)", source)+ assert substitutions == 1, "TypeScript verifier signature changed; update the annotation strip"++ driver = tmp_path / "driver.js"+ driver.write_text(+ 'const crypto = require("crypto");\n\n'+ f"{source}\n"+ + textwrap.dedent(+ """+ const spec = JSON.parse(process.argv[2]);+ const rawBody = Buffer.from(spec.rawBody, "base64");+ const verdicts = {};+ for (const [label, signature] of spec.cases) {+ verdicts[label] = verifySkyvernSignature(rawBody, signature === null ? undefined : signature);+ }+ console.log(JSON.stringify(verdicts));+ """+ ),+ encoding="utf-8",+ )++ return ["node", str(driver), SPEC]+++def _go_driver(tmp_path: Path) -> list[str]:+ source = _extract("go", r"^func verifySkyvernSignature\b.*?^\}\n")++ driver = tmp_path / "main.go"+ driver.write_text(+ textwrap.dedent(+ """\+ package main++ import (+ "crypto/hmac"+ "crypto/sha256"+ "encoding/hex"+ "encoding/base64"+ "encoding/json"+ "fmt"+ "os"+ )++ """+ )+ + f"{source}\n"+ + textwrap.dedent(+ """+ func main() {+ var spec struct {+ RawBody string `json:"rawBody"`+ Cases [][]*string `json:"cases"`+ }+ if err := json.Unmarshal([]byte(os.Args[1]), &spec); err != nil {+ panic(err)+ }+ rawBody, err := base64.StdEncoding.DecodeString(spec.RawBody)+ if err != nil {+ panic(err)+ }+ verdicts := map[string]bool{}+ for _, c := range spec.Cases {+ signature := ""+ if c[1] != nil {+ signature = *c[1]+ }+ verdicts[*c[0]] = verifySkyvernSignature(rawBody, signature)+ }+ out, _ := json.Marshal(verdicts)+ fmt.Println(string(out))+ }+ """+ ),+ encoding="utf-8",+ )++ return ["go", "run", str(driver), SPEC]+++RUNTIMES = [("node", _typescript_driver), ("go", _go_driver)]++[email protected]("runtime,build_driver", RUNTIMES, ids=[r[0] for r in RUNTIMES])+def test_snippet_rejects_forged_and_missing_signatures(+ runtime: str, build_driver: Callable[[Path], list[str]], tmp_path: Path+) -> None:+ _require_runtime(runtime)+ verdicts = _run_driver(build_driver(tmp_path), tmp_path)+ assert verdicts is not None+ _assert_verdicts(verdicts)++[email protected]("runtime,build_driver", RUNTIMES, ids=[r[0] for r in RUNTIMES])+def test_snippet_does_not_accept_when_api_key_is_absent(+ runtime: str, build_driver: Callable[[Path], list[str]], tmp_path: Path+) -> None:+ """An unset key must not sign with "" -- a key an attacker also knows."""+ _require_runtime(runtime)+ verdicts = _run_driver(build_driver(tmp_path), tmp_path, api_key=None)+ if verdicts is None:+ return # refused to run without a key, which is also fail-closed+ assert verdicts["forged_with_empty_key"] is False, (+ f"the {runtime} verifier signs with the empty key when SKYVERN_API_KEY is unset, "+ "so anyone can forge a valid signature"+ )+ assert verdicts["genuine"] is False+++# A discarded timingSafeEqual call and a timing-unsafe equality compare: the two shapes+# that made the published verifiers permissive. Neither may reappear in any docs page.+DISCARDED_TIMING_SAFE_EQUAL = re.compile(r"^\s*(?:crypto\.)?timingSafeEqual\(", re.M)+UNSAFE_SIGNATURE_COMPARE = re.compile(+ r"signature[^\n=!<>]*={2,3}[^\n]*expected|expected[^\n=!<>]*={2,3}[^\n]*signature"+)++[email protected]("doc", sorted(REPO_ROOT.joinpath("docs").rglob("*.mdx")), ids=lambda p: p.name)+def test_docs_contain_no_permissive_signature_check(doc: Path) -> None:+ text = doc.read_text(encoding="utf-8")+ assert not DISCARDED_TIMING_SAFE_EQUAL.search(text), (+ f"{doc.relative_to(REPO_ROOT)} calls timingSafeEqual as a statement; its return value must be used"+ )+ assert not UNSAFE_SIGNATURE_COMPARE.search(text), (+ f"{doc.relative_to(REPO_ROOT)} compares a signature with ==; use a constant-time comparison"+ )