Webhook Signature Checks for AI Agents: Verify Before Acting
Learn how to verify webhook signatures before an AI agent acts on an event, covering raw body checks, replay windows, deduplication and approval boundaries.

To verify a webhook signature before an AI agent acts, recompute the signature over the exact raw request body using the secret shared with that sender, compare the two values in constant time, and reject any event whose timestamp falls outside the window the sender documents. Only events that pass these checks should reach the agent, and the agent should treat the payload as data to classify rather than as a new instruction.
Key takeaways
- Verify the signature on the raw request body before any parsing, rewriting or handoff to the agent.
- Use a separate secret for each sender and environment, and compare signatures in constant time.
- Reject old timestamps and repeated event identifiers so that a captured event cannot be replayed.
- Allowlist the event types the agent may read, and keep every write behind an approval boundary.
- Log each rejected event with its source, time and reason so that failures are visible to the owner.
Why an unsigned webhook opens a path for spoofed instructions
A webhook is an HTTP request that another system sends to your endpoint when something happens, such as a payment failing, a form being submitted or a ticket changing status. The endpoint is only a URL, and URLs leak. They appear in logs, configuration files, shared documents and vendor dashboards. If the agent treats anything that arrives at that address as a true event, whoever finds the address can make the agent believe that an order was cancelled or that a supplier changed its bank details.
Signature checks close that path. The sender computes a keyed hash over the event using a secret that only the sender and your endpoint hold, and sends the result in a header. Your endpoint recomputes the hash and accepts the event only when the two values match. A valid signature shows that the request came from a holder of the secret and was not altered in transit. It does not prove that the content is accurate or safe, and that difference shapes the rest of the design.
How to verify a webhook signature before the agent acts
The order of these steps matters as much as the cryptography. Run them at the edge of your system, before anything reaches the agent's context window or its tools:
- Read the raw request body as bytes, before any JSON parser or framework middleware rewrites it.
- Extract the signature and, where the sender provides one, the timestamp from the headers, following the format in the sender's documentation.
- Compute the expected signature with the secret assigned to that specific sender and environment.
- Compare the two values with a constant-time comparison function, never with a plain string equality check.
- Reject the request if the timestamp falls outside the tolerance window the sender describes, which limits replay of old events.
- Check the event identifier against recently processed identifiers and stop if the event was already handled.
- Parse the JSON only after the checks pass, then confirm the event type appears on the list this agent may handle.
- Pass a normalized event to the agent with its source, received time and event type attached, and let the normal permission checks govern any action that follows.
Most of these steps take little code. The common failures come from skipping them for a convenient test route or re-serializing parsed JSON before checking the signature, which changes whitespace and key order so that valid events fail. Teams then disable the check to get the flow working, and the door stays open. Other frequent gaps include sharing one secret across staging and production, accepting unsigned requests on a route that is still reachable, logging full headers that expose the secret, and trusting a payload field such as a source label, which the sender controls.
Stripe documents how it signs webhook events and how a receiving server should verify them, including the role of the timestamp in the signed content. Read the vendor's own description for every system you connect, because header names, encodings and tolerance behavior differ. A snippet copied from a forum is not a substitute for the provider's documentation. If you are still choosing between push and pull for a workflow, webhooks vs polling for AI workflows sets out the trade-offs before you build the intake.
The signature proves the sender, not the content
A correctly signed event can still carry text that tries to steer the agent. A customer note, a ticket description or a free-text form field can contain a sentence written as an instruction. OWASP's guidance on prompt injection prevention treats external content as untrusted input, including content that arrives through a channel you control. The practical response is architectural. Put payload fields in a clearly marked data section of the agent's input. Instruct the agent that those fields are records to classify, not commands. Keep its outputs as proposals. Require a named approver for any write. Keep tool permissions narrow, so that a manipulated reasoning step cannot reach a tool the task never needed.
Illustrative scenario: a store receives a correctly signed event reporting a failed card payment. The customer note in the payload asks the agent to cancel the order and issue a refund. The agent classifies the event as a payment failure, drafts a reply for the support lead and records the note as a customer request. No refund moves until a named approver confirms it in the approval channel. The signature check confirmed where the event came from, and the permission design decided what the agent could do with the words inside it. The same pattern applies to read, draft and send permissions, where drafting is allowed but sending is a separate grant.
Which events may reach an agent, and in what form
Verification is a gate, and the gate should be paired with a decision for each event type. A simple guide for an operations team looks like this:
- Status events, such as a delivery update, can reach the agent as read-only context for summaries and lookups.
- Intake events, such as a new inbound lead, can reach the agent with permission to classify and draft a response.
- Events that would trigger a write, such as an invoice creation or a refund, should produce a proposal that a person approves before any tool changes a record.
- Events from a source without a verifiable signature should not reach the agent at all, and should go to a review queue owned by a person.
- Event types nobody has reviewed should be dropped and logged until someone adds them to the allowlist with a named owner.
A valid event can also arrive more than once, because senders retry delivery when they do not receive a timely response. Keep the duplicate check connected to the write path, not only to the intake step. The idempotency guidance for agent actions explains how to make a repeated event produce one effect.
How Be Human handles webhook intake in a managed engagement
In a Be Human engagement, webhook intake is part of the integration design rather than an afterthought. The team defines which events the agent may read, configures a separate secret and verification step for each sender and environment, sets the deduplication and allowlist rules, and documents which actions remain behind an approval boundary. Managed operations then review rejected-event logs during permission reviews, respond to failures as incidents, rotate secrets on a schedule agreed with the client, and reopen the design when a vendor changes its signing format or event schema. The aim is an intake path that a business owner can inspect, not one that depends on a single developer remembering how it works.
Testing and operating the check after launch
Before go-live, send a correctly signed sample event, then the same body with one character changed, an event with an old timestamp, a repeated event identifier and an event type that is not on the allowlist. Each case should produce the outcome you designed for, and each should leave a log entry with the source, time and reason, without the secret itself. Repeat the same test after every vendor change, because signing formats and payload schemas change over time. Then choose the first event worth handing to an agent by picking one event type, one named owner and one observable check that shows whether the result was correct. If you are not sure which event that should be, the free Be Human AI diagnostic can help you find that first task.
Frequently asked questions
Do I still need signature checks if my webhook URL is hard to guess? A hidden URL is not an authentication method, because addresses appear in logs, configuration files and shared documents. A signature check is inexpensive to implement and proves that the sender holds the secret. Keep the URL unguessable, but do not rely on that alone to decide what the agent should trust.
What signature method should I expect from a provider? Many providers use a keyed hash such as HMAC with SHA-256, but the header name, the signed content and the tolerance rules differ from one vendor to another. Some providers publish public keys for asymmetric verification instead. Follow the vendor's documentation for each source, and test with a sample event before connecting it to an agent.
What should the agent do when verification fails? The endpoint should reject the event without passing any part of it to the agent, return the status the protocol expects where that is possible, and log the source, time and reason without storing secrets. Repeated failures from one source should alert the person who owns the integration. The agent should never try to interpret a rejected event, because the purpose of the check is to keep unverified content out of its context.
Does signature checking replace approvals for writes? No. Signature checking tells you who sent the event, while approvals decide whether the agent may act on what the event says. A verified sender can still send stale data or a misleading instruction, and a signed event can contain text that should never become a refund or a bank change without a person confirming it. Keep both controls in place.
Your next step
See where an AI agent fits in your company first.
Take the free Be Human AI diagnostic. A few questions about your work show which task to hand to an agent first, what it needs to know and where a person approves.
Be Human editorial guidance. Examples are illustrative unless explicitly attributed. Sources provide background; implementation choices depend on your workflow.


