How to Trigger AI Agents from Webhooks: Signature Verification, Retries, and Idempotency

Webhooks allow AI agents to react immediately to events happening elsewhere, rather than waiting to be polled for updates. This reactiveness comes with increased risk, as a corrupted webhook can trigger undesired real-world actions from the agent. Three key factors must be right before an agent can safely act on an incoming webhook event: verifying the signature genuinely came from the provider, blocking replayed events, and deduplicating retries using idempotency keys.

Verifying the signature is essential - a bad payload is an action problem, not just a data quality issue. The standard approach is HMAC SHA256, where the provider and server share a secret key and compare hashes of the request body (with timestamp). This must be done with a constant time comparison function to prevent timing attacks.

However, raw body parsing issues commonly break this verification, as frameworks like Express parse the body before the handler sees it, leading to mismatched hashes. The fix is to capture the raw body first, before any parsing occurs. Blocking replay attacks is also critical. An attacker can intercept a genuine signed payload and resend it later, causing the same action to be performed multiple times.

The solution is to check the timestamp included in the signature and ensure it is within a short freshness window (often 5 minutes). The timestamp is folded into the hash string, so changing it invalidates the signature. Handling retries is necessary, as webhook providers guarantee at least once delivery. Respond with a 2xx status immediately after signature verification, before any agent logic runs.

This allows the provider to retry without triggering duplicate agent actions. Idempotency keys further ensure that if an event is delivered multiple times, the agent only performs the action once, even if the same request is retried.