Skip to content

Automate browser based workflows with AI

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.mdx
index 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.mdx
index 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 block
diff --git a/docs/developers/going-to-production/webhooks.mdx b/docs/developers/going-to-production/webhooks.mdx
index 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.mdx
new file mode 100644
index 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.py
new file mode 100644
index 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"
+ )