Skip to content
be-human.ai
← Back to the journal

Tools & integrations

Webhook Signature Checks for AI Agents: Reject Forged and Replayed Events

Verify webhook signatures over the raw body, check timestamps, and store event IDs so an AI agent acts only on fresh, unseen, authentic inbound events.

Be Human typographic cover with the title: Webhook Signature Checks for AI Agents: Reject Forged and Replayed Events
Conceptual illustration created with AI · Be Human

To verify a webhook signature for an AI agent, recompute an HMAC over the exact raw request body using the secret the sender gave you, compare it in constant time with the signature header, and confirm the timestamp is recent. Then store the provider's event ID so a redelivered or replayed request cannot trigger the agent a second time. Only verified, new events should reach the model, and the agent should act on them only through tools its role allows.

Key takeaways

  • Verify the signature over the raw request body, before any parsing, reformatting or framework middleware touches it.
  • Compare signatures in constant time, and reject any event whose timestamp falls outside your tolerance window.
  • Deduplicate by the provider's event ID, because legitimate redeliveries look like replays to a naive handler.
  • Treat every field in the payload as untrusted text, and let the agent act only through scoped, approved tools.
  • Log every rejection with a reason, since rejections reveal misconfigurations, expired secrets and probing.

Why an agent needs more checks than a simple webhook handler

A webhook handler that writes a row to a table fails in a limited way. An agent is different. It reads the event, reasons about it, and may call tools that send a message, draft an invoice or change a record. A forged event then becomes a request to act, which is why the inbound path needs to answer three separate questions before the agent sees anything.

The first question is authenticity: did the sender hold the shared secret? The second is freshness: was the request sent recently, or is someone resending an old capture? The third is uniqueness: has this event already been processed? A valid signature answers only the first question. Even a perfectly signed event can contain a request the agent should not fulfil, so authorization for the actions that follow still belongs to the tool layer. Our guidance on least privilege for AI agents covers that second boundary in more detail.

Step-by-step: verify the signature before the agent sees the event

The order of operations matters. Each step should finish before the next one begins, and a failure at any point should stop processing with a logged reason. A practical sequence looks like this:

  • Configure the route that receives events to expose the raw body. Disable any global JSON middleware that parses and re-serializes the body for this path, because a changed space or key order will break the HMAC.
  • Read the signature header and the timestamp exactly as your provider documents them. Some providers sign the timestamp together with the body, and others sign only the body. Follow the provider's scheme, not a scheme you remember from another integration.
  • Load the shared secret for this endpoint from a secrets store. Keep it out of prompts, agent memory, configuration files that people copy around, and application logs.
  • Compute the HMAC with the algorithm the provider specifies, then compare it with the received value using a constant-time comparison function, not a plain string equality check.
  • Check the timestamp against a tolerance window. Reject events that are too old, and reject timestamps that are unreasonably far in the future, since clock problems and tampering both produce them.
  • Only after every check passes, parse the JSON and validate it against the schema for that event type. Unknown or malformed fields should stop the flow here rather than being passed along.
  • Acknowledge the delivery with a success response, then place the verified event on the agent's processing queue. Doing the slow reasoning after the acknowledgement keeps the endpoint responsive, and it avoids timeouts that trigger redelivery.

For the provider side of this pattern, the [Stripe webhook documentation](https://docs.stripe.com/webhooks) shows a concrete implementation of signed deliveries with timestamps, and it is a useful reference even if your provider is different.

How to reject replayed events

A replay happens when someone captures a valid signed request and sends it again. The timestamp check narrows the window in which that is possible, but it does not close it. Inside the window, the same valid request will still pass the signature test, so you need a second control.

That control is an event ID store. Each provider event carries a unique identifier. Before the agent processes an event, insert that identifier into a table that enforces uniqueness. If the insert fails because the identifier already exists, acknowledge the delivery, take no action and log the event as a duplicate. The insert and the processing state should be recorded together, so a crash between verification and action does not leave an event marked as handled when it was not, or the reverse.

Retention matters. Keep identifiers at least as long as your tolerance window plus the provider's documented redelivery period. Check how long the provider keeps retrying a failed delivery, because a record that expires too early reopens the door to a second action. The same idea appears in our note on idempotent actions for AI agents, which applies the principle to the writes the agent makes, not only to inbound events.

A decision guide for rejected and suspicious events

The handler should choose one outcome for every delivery. A simple decision guide keeps those outcomes consistent across integrations:

  • Signature header missing or malformed: reject, log the endpoint and reason, and count the event toward an alert threshold.
  • Signature does not match: reject without processing, log the reason, and notify the person responsible for the integration.
  • Timestamp outside the tolerance window: reject, log it as a possible replay, and review the source if the pattern repeats.
  • Event ID already recorded: acknowledge without action and log it as a duplicate.
  • Signature valid, event new, schema validation fails: store the payload in a restricted review area, do not let the agent act, and notify an owner.
  • Signature valid, event new, schema passes: pass the parsed fields and verification metadata to the agent, and let the tool permissions decide what it may do next.

Notice that only the last outcome reaches the agent's reasoning. Every other path ends before the model is involved, which keeps the agent's context free of data that failed verification.

Verification decides whether the event is real and new. Permissions decide whether the agent may act on it.

Treat the payload as data, not as instructions

An authentic webhook can still carry hostile or careless text. A customer may write a message in a form field, a support ticket may include a pasted instruction, or a document name may contain a sentence aimed at a model. The [OWASP Top 10 for LLM Applications](https://genai.owasp.org/llm-top-10/) lists prompt injection as a central risk for exactly this reason. The defense is structural: the agent's operating instructions come from its configured role, the event arrives as clearly labeled data, and every consequential action passes through a tool that enforces its own permissions regardless of what the model concluded.

Illustrative scenario: a payment provider sends a signed event saying an invoice was paid. The signature and timestamp checks pass, and the event ID is new. The agent updates its own task list and drafts a reconciliation note for the finance team. Posting the payment to the accounting system waits for a named approver, because the agent's role allows drafts but not postings. If the event description had contained an instruction to post anyway, the tool would still refuse, because the permission is held by the tool, not by the text.

For approvals, a Slack approval flow for agent actions is one common way to put a named person between a drafted write and the live system.

How Be Human handles inbound verification in a managed engagement

Be Human treats the inbound path as part of the agent's infrastructure, not as a side script. In a managed engagement, the verification secret sits in a controlled store with access limited to the integration. Signature, timestamp and deduplication checks run before the agent receives any event, and the agent's tools carry the approval boundaries defined for its role. Monitoring tracks rejection counts and unusual patterns, permission reviews confirm which tools the agent can still reach, and incident response follows a written path if a secret is exposed or a replay pattern appears. Each agent keeps a named identity, which makes its actions traceable in the systems it touches.

Test the inbound path before the agent goes live

Testing should cover the failure paths, because those are where a first version usually breaks. Before connecting a live provider, check the following:

  • Send a correctly signed event and confirm it reaches the agent once.
  • Send the same event again and confirm the second delivery is acknowledged and not processed.
  • Alter one byte of the body and confirm the signature check rejects it.
  • Send an event with an old timestamp and confirm it is rejected with a timestamp reason.
  • Remove the signature header and confirm the rejection is logged without storing the full body.
  • Rotate the secret in a test environment and confirm the endpoint accepts the new value and refuses the old one.

After launch, review the rejection log on a regular schedule, rotate secrets according to a documented plan and when people with access change roles, and run recurring evaluations on how the agent handles unusual but valid events. Keep the logs to what you need: the endpoint, the event ID, the result and the reason code are usually enough, and personal data in full payloads should be stored only when there is a clear purpose.

If you are unsure which inbound event is the right first one to hand to an agent, take the free Be Human AI diagnostic to find the first task worth handing to an agent.

Frequently asked questions

Do I need signature checks if my provider is well known? Yes. A reputable provider protects its own side of the channel, but your endpoint is a separate system with its own exposure, and an unsigned or unchecked route can be called by anyone who discovers its address. Signature verification confirms that the request came from someone holding the secret, which is the minimum condition for trusting it.

Is a timestamp check enough to stop replays? It narrows the window but does not close it, because a captured request remains valid for the length of the tolerance period. Pair the timestamp check with a store of processed event IDs, so a second delivery of the same event is recognized and ignored even inside the window.

Should the agent receive the raw webhook body or a parsed copy? The agent should receive a parsed copy that has passed schema validation, containing only the fields its task needs. Keep the raw body in a restricted store for audit or dispute review if your process requires it, and avoid placing it in prompts where unnecessary personal data or hostile text could reach the model.

What if my platform already verifies webhooks for me? Confirm exactly which layer performs the check, whether it covers timestamps and deduplication, and what it does with events that fail. Even when the platform verifies signatures, the agent still needs its own schema validation, idempotent handling and approval boundaries, because those protect against errors and injected content that a signature check cannot detect.

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.

Less busywork. More room for you.

Bring us the work you wish you had time for.

Book a call to try a personalized AI agent free for 7 days ↗Or take the free AI diagnostic →