Skip to main content
Velor
All resources
EngineeringApril 2026 · 5 min read

Why we sign every API action instead of giving the agent direct access


When you build an AI agent that can take actions — look up an order, cancel a subscription, issue a refund — the obvious implementation is to give the agent an API key and let it call your API directly. This works in demos. At production scale, it creates a risk profile that most teams don't fully think through until something goes wrong. Here's the threat model and why we built the signing layer instead.

The obvious approach

You provision an API key with the permissions the agent needs. You store it in the agent's configuration. The agent makes API calls directly when a customer asks about their account. Simple, and it works fine for low-volume internal tools where the agent's input is controlled.

The problem surfaces when the agent is handling thousands of conversations per day from untrusted users — which is the entire premise of customer-facing support.

The threat model at scale

Two things become statistically likely when a customer-facing agent handles volume. The first is prompt injection: a user's message contains text that tricks the agent into calling an API it shouldn't, or calling a legitimate API with parameters it shouldn't use. LLMs are susceptible to this in ways that are difficult to fully patch at the prompt level. The second is action creep: as the agent's instructions evolve over time through edits and additions, it gradually starts calling endpoints or passing parameters outside the originally intended scope.

With a directly-held API key, both risks have immediate blast radius. The key is live, the call authenticates, and the action executes before anyone can review it. In a write-capable context — a cancellation endpoint, a charge adjustment, a deletion — that means irreversible outcomes from a single misfire.

What signed webhooks change

For custom webhook actions, Velor never holds your API credentials. (The built-in connectors are different: you paste an API key, and Velor stores it encrypted and calls that API itself.) Instead, you register an action by providing a JSON schema that defines exactly what the endpoint is, what parameters are valid, and whether the action is destructive. Every call from the agent goes through Velor's signing layer: we generate an HMAC-SHA256 signature using a shared secret that Velor generates when the action is created and stores encrypted, and we include a timestamp. Your endpoint receives the request, verifies the signature, and checks that the timestamp is within a 5-minute window before executing.

The immediate consequence: even if prompt injection causes the agent to construct a request with unexpected parameters, your endpoint can inspect and reject at the boundary. You own the verification logic. For a custom webhook action, Velor never has access to the credentials that actually authorize the action — it only has a shared secret for proving that a particular request came from a particular registered action.

Rate limits and the destructive flag

Action calls are rate limited by Velor (10 per conversation per hour and 500 per minute per workspace; these are fixed, not set per action), and every action registration includes a destructive boolean. When destructive is true, the agent requires explicit user confirmation before calling the action. In the conversation, this appears as a confirmation card showing the exact parameters, which the visitor taps Confirm on in the chat widget — the agent will not call the endpoint until they do. On voice, SMS, WhatsApp, email and Slack there is nothing to tap, so the action waits for a teammate's approval instead.

This is a UX guardrail, not a security guarantee. A determined bad actor can confirm an action. But for the far more common case — accidental trigger from ambiguous phrasing, misread context, or an escalation path that hits a destructive action unexpectedly — it catches the misfire before it executes. It also creates a log entry showing what the agent was about to do and what confirmation it received.

The schema as a contract

The JSON schema you register for an action isn't just input validation. It defines the only surface the agent can call. If a parameter isn't in the schema, the agent has no mechanism to pass it. If the endpoint isn't in the schema, the agent can't call it.

This narrows the attack surface of prompt injection from “any API call the agent's key can make” to “this specific endpoint with these specific validated parameters.” A maliciously crafted message can still try to pass a bad customer ID or an out-of-range parameter, but it cannot call a different endpoint entirely or pass a parameter type your schema rejects. The schema acts as a static policy layer that doesn't depend on the agent's instructions being perfect.

What this doesn't protect against

HMAC signing solves the authentication and boundary problems. It doesn't solve semantic errors. If the agent calls cancel_subscription with the correct customer ID because it misread conversational context — the customer said “I might cancel” and the agent treated it as intent — the signature will verify and the action will execute. The request is well-formed; it's just wrong.

That's where escalation guardrails and conversation-level intent detection come in — a separate layer that operates before the action is dispatched. Signing addresses the authentication and scope boundary. Guardrails address the semantic layer. Neither replaces the other. Defense in depth means both are in place, not one standing in for the other.

Numbers in this post that cite no source are rules of thumb, not Velor measurements. Velor has no customer deployment to measure yet.

Velor

Want to see how this applies to your support queue?

Send us your recent tickets — at least 300, ideally 500 — and get a resolution rate, before you commit to anything.

14-day free trial · no credit card