Protect AI agent tool webhooks with per-call tokens

AI AgentsAI agent tool webhook authentication

Mint a token for each call and AI agent tool, then reject missing, expired, edited, or mismatched tokens.

security

The claim

Every tool renders its web_hook_url with a __token query parameter minted for this call and this function. The endpoint refuses a token from another call, for another function, altered, or expired, and the handler does not run. The two tools in this recipe never set secure; the tokens are the default.

Why it holds

The SDK checks a token only when one is present. A request that omits it, or sends an empty one, is not refused by the token layer. The basic-auth credentials that gate the route sit in the same URL an attacker captured, so they do not close that gap either. This agent adds one rule of its own: no token, no handler.

How it works

You write nothing to get the tokens. The document rendered for a call carries, per function:

{"function": "issue_refund",
 "web_hook_url": "https://user:pass@host/accounts/swaig/?__token=Y2FsbC1BLmlz..."}

The SDK’s SessionManager (signalwire/core/security/session_manager.py) mints the token. It is an HMAC over the call id, the function name, an expiry and a nonce, signed with a key generated when the process starts. Its validate_token checks the function name, then the expiry, then recomputes the signature, then compares the call id. Any mismatch returns a refusal in the function result, and the handler does not run.

The rule you add sits on the app the SDK builds:

app = agent.get_app()

@app.middleware("http")
async def require_token(request, call_next):
    if request.url.path.rstrip("/") == tool_path and request.method == "POST":
        if not request.query_params.get("__token"):
            return JSONResponse(status_code=403,
                                content={"response": "A per-call token is required."})
    return await call_next(request)

The test is not ...get("__token"), not a key check. A request with ?__token= has the key, and the SDK treats the empty value as no token at all. In the SDK, serve() runs the app that get_app() built and cached, so the middleware sits in front of every tool request. token_expiry_secs on the constructor sizes the window: the SDK default is 3600 seconds, and this recipe sets 900 through TOKEN_TTL_SECONDS.

Limitations

The middleware is the recipe’s rule, not the SDK’s. Without it, a request with no token reaches the handler as soon as it passes basic auth.

Your process generates the signing key at start. AgentBase.__init__ builds the SessionManager with only token_expiry_secs, so there is no constructor argument to share a key. Two replicas behind a load balancer will each refuse the other’s tokens.

What to change first

Delete the require_token middleware and run the verifier. The last check fails: a request with no token now runs issue_refund, which is the gap this recipe exists to close.

Where this sits

Before this

Give a voice AI agent a tool

Require verification before unlocking AI agent tools

python/app.py

"""Protect tool webhooks with per-call tokens.

Every tool webhook URL the platform receives carries a token minted for this
call and this function: an HMAC over call id, function name, expiry and a
nonce, signed with a key that lives only in your process. The SDK refuses a
token minted for another call, for another function, after expiry, or with a
character changed.

The SDK checks a token only when one is present. A request that omits it, or
sends an empty one, is not refused by the token layer, and the basic-auth
credentials that would refuse it are embedded in the same URL an attacker
captured. So this agent adds one rule of its own, on the app the SDK builds: a
request to the tool endpoint with no token is refused before any handler runs.

Written against signalwire-sdk 3.0.1.
"""
import os

from dotenv import load_dotenv
from fastapi import Request
from fastapi.responses import JSONResponse
from signalwire import AgentBase, FunctionResult

# the SDK does not read .env for you
load_dotenv()

# How long a token stays valid after the document is served. The SDK default
# is an hour (token_expiry_secs=3600); this recipe shortens it to fifteen
# minutes. A call that can run longer needs a longer window.
TOKEN_TTL_SECONDS = int(os.getenv("TOKEN_TTL_SECONDS", "900"))

ACCOUNTS = {"48815": {"name": "Dana Whitfield", "balance": 42.10}}

# Every handler run is recorded here, so a test can prove a refused request
# never reached one.
HANDLER_RUNS = []


class AccountAgent(AgentBase):
    def __init__(self):
        # token_expiry_secs sizes the window every per-call token is valid for
        super().__init__(name="accounts", route="/accounts",
                         token_expiry_secs=TOKEN_TTL_SECONDS)
        self.prompt_add_section(
            "Role",
            "You help callers with their account at a bicycle shop. Look the "
            "account up before quoting anything. Only refund when asked.",
        )

    # secure=True is the default on every tool below: each one's webhook URL
    # carries a token bound to the call the document was rendered for.

    @AgentBase.tool(
        name="get_balance",
        description="Look up an account's balance by account number.",
        parameters={
            "type": "object",
            "properties": {
                "account_id": {"type": "string",
                               "description": "The five digit account number."}
            },
            "required": ["account_id"],
        },
    )
    def get_balance(self, args, raw_data):
        HANDLER_RUNS.append("get_balance")
        acct = ACCOUNTS.get((args.get("account_id") or "").strip())
        if not acct:
            return FunctionResult("NOT_FOUND: no such account. Ask for the "
                                  "number again.")
        return FunctionResult(f"{acct['name']} has a balance of "
                              f"{acct['balance']:.2f}.")

    @AgentBase.tool(
        name="issue_refund",
        description="Refund the account's balance to the card on file.",
        parameters={
            "type": "object",
            "properties": {
                "account_id": {"type": "string",
                               "description": "The five digit account number."}
            },
            "required": ["account_id"],
        },
    )
    def issue_refund(self, args, raw_data):
        HANDLER_RUNS.append("issue_refund")
        acct = ACCOUNTS.get((args.get("account_id") or "").strip())
        if not acct:
            return FunctionResult("NOT_FOUND: no such account.")
        # A real handler would call your payments API here.
        return FunctionResult(f"Refunded {acct['balance']:.2f} to the card on "
                              f"file for {acct['name']}.")


def build():
    """The agent, plus the one rule the SDK leaves to you."""
    agent = AccountAgent()
    app = agent.get_app()
    tool_path = agent.route.rstrip("/") + "/swaig"

    @app.middleware("http")
    async def require_token(request: Request, call_next):
        # The SDK validates a token when one is present. This closes the gap
        # where a request carries none, or an empty one: it never reaches a
        # handler. `not ...get()` refuses both; a key check alone would let
        # `?__token=` through, and the SDK treats an empty value as absent.
        if request.url.path.rstrip("/") == tool_path and request.method == "POST":
            if not request.query_params.get("__token"):
                return JSONResponse(
                    status_code=403,
                    content={"response": "A per-call token is required."},
                )
        return await call_next(request)

    return agent


agent = build()

if __name__ == "__main__":
    agent.serve(host="0.0.0.0", port=int(os.getenv("PORT", "3000")))

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # set SWML_BASIC_AUTH_PASSWORD
python app.py

The webhook needs a public HTTPS URL. For a local run, expose port 3000 with a tunnel such as ngrok and use that hostname. Point a number’s SWML webhook at https://<user>:<password>@<your-host>/accounts/.

Verify it

No network, no account. The verifier drives the agent’s own HTTP app with FastAPI’s test client, the way the platform would, and records every handler run.

python verify.py          # from the recipe folder, not python/

It renders the document for one call, takes the refund tool’s token off its URL, and POSTs to the tool endpoint, asserting the following.

both tools, which never set secure, render with distinct tokens
without basic auth the route answers 401 and nothing runs
each tool’s token, on its own call and function, runs that handler once and returns its text
a token on another call, on the other function, or with a character changed gets the SDK’s refusal and runs nothing, in both directions
a token minted with a closed expiry window gets the same refusal
a request with no token, and one with an empty token, each get a 403 from the middleware and run nothing

The verifier never prints a URL, because the URLs carry your basic-auth credentials.

Report an issue