Verify the VAPI webhook, so a forged transcript is refused

[buildbyjithu]

Closes ENG-3544 for Python. Stacked on #4, which adds the bridge this verifies. Mirrors deeptrust-ai/deeptrust-typescript#3.

Summary

The bridge took any POST. A customer's webhook is a public URL, so anyone who learned it could post a transcript event for a call that never happened, or words never said in one that did, and have it become a real call, a real analysis and a real finding in their DeepTrust organization. A forged end-of-call-report could also end a real call's session early.

VAPI already sends server.secret back in X-Vapi-Secret on every request. This turns that into a check.

bridge = Bridge(
    DeepTrust(),
    api_key=os.environ["VAPI_API_KEY"],
    secret=os.environ["VAPI_WEBHOOK_SECRET"],
)

@app.post("/vapi/webhook")
async def vapi_webhook(request: Request, payload: dict):
    try:
        await bridge.handle(payload, user=caller, headers=request.headers)
    except WebhookVerificationError:
        raise HTTPException(status_code=401)
    return {}

A request that does not carry it raises WebhookVerificationError before a turn is appended or a session is created.

Choices

• hmac.compare_digest for the compare, so a caller cannot learn the secret one character at a time from how long the refusal took.
• The header is read case-insensitively. Starlette hands over a case-insensitive mapping, but a plain dict is a reasonable thing for a caller to pass and it should not silently fail to match.
• Verification is off when no secret is configured, so an existing integration keeps working. The README and the module docstring both say what that costs rather than leaving it implied.

Testing

just check clean: ruff, ruff format, mypy, 42 tests passing, 5 of them new.

The new ones cover a request without the secret refused with nothing recorded (no analyze call, no session), a wrong secret refused, the right secret accepted and returning an analysis, no configured secret keeping existing behaviour, and the header read case-insensitively.

Parity note

The TypeScript version hand-rolls its constant-time compare because that module has to run on Node, Bun, Deno and the edge, where crypto.timingSafeEqual is Node-only. Python has hmac.compare_digest in the standard library, so this uses it. Same behaviour, same refusal, same header.

🤖 Generated with Claude Code

---

[devin-ai-integration]

Devin Review found 1 potential issue.

1 bug not posted on this PR by your GitHub settings — view it in Devin Review. (Configure)

[devin-ai-integration]

🟨 Webhook authentication defaults to disabled

Omitting or emptying secret makes verify accept every request. Misconfigured deployments remain open to forged transcripts and premature call termination.

---

Was this helpful? React with 👍 or 👎 to provide feedback.