When an AI coding assistant adds a webhook endpoint, review the path from the incoming request to the first business effect. Establish that the handler verifies the provider’s signed message before it creates a job, changes a record or sends a notification. Then check what the authenticated event is actually allowed to change.
A webhook is an HTTP request that another system sends when something happens. It can connect payments to access, a delivery service to order status, or a repository event to a build. An endpoint that accepts a convincing JSON object without authenticating its source can turn an ordinary web request into a business instruction.
This guide proposes a review method for AI-generated integration code. The worked scenario is fictional; no webhook implementation, provider SDK or coding assistant was tested for this article. The aim is to help an engineering owner define evidence for a particular integration, rather than approve generated code because its happy-path example returns success.
Identify the first effect before reviewing the parser
Consider a fictional training business. A payment provider sends an event to an application that activates access to a purchased course. An assistant has drafted the handler, a test fixture and a test expecting an HTTP success response.
Start the review by finding the first effect: an access grant, a database write or a queued job that will eventually grant access. Trace backward from that point. Which verified event reaches it? Where is the endpoint secret selected? Can a verification exception fall through into ordinary processing? Does a catch block acknowledge the request after work has already begun?
Ask the assistant to identify those locations in the existing code and configuration. Inspect the actual middleware order as well as the handler function. A verifier call in the diff is insufficient if another route bypasses it, the wrong object reaches it, or the error branch continues execution.
Keep the investigation bounded. This is a review of one incoming integration, not permission for an agent to retrieve production secrets or trigger real purchases. Use an isolated test environment and synthetic records under the team’s established access rules.
Preserve what the sender signed
Stripe’s current endpoint troubleshooting documentation requires its raw request body, signature header and endpoint secret for verification. It warns that frameworks can change the body through parsing, whitespace removal, key ordering or encoding. It also distinguishes a CLI-forwarded endpoint’s secret from a Dashboard-managed endpoint’s secret.
That distinction creates a useful review question: does the verifier receive the delivered representation or a reconstruction of it? Parsing JSON and serializing the resulting object can preserve the apparent business fields while changing the message being authenticated.
For the fictional course integration, keep an exact, synthetic request fixture suitable for the provider’s documented verification method. Preserve its body and required headers together. A test that creates a fresh signature from whatever body the handler reconstructs can conceal the mismatch it was supposed to expose.
Use a valid baseline and deliberately altered variants. Change the delivered body while retaining the original signature; verification should reject it. Separately, sign an alternate valid representation according to the provider’s test procedure and confirm the supported request path accepts it. These are different cases: tampering with an already signed message versus receiving another properly signed message.
Follow the provider’s protocol. Do not ask an assistant to invent a universal JSON normalization step to make mismatched signatures pass. A framework adapter, proxy or body parser needs its own check against the documented representation.
Avoid turning cryptographic details into improvised glue
GitHub’s webhook validation guide documents its HMAC-based signature header and recommends a constant-time comparison instead of ordinary equality. It also says to keep the secret out of application source and repositories. These are GitHub-specific verification instructions, not proof that the same header format or signed fields apply to another provider.
Ask which maintained verification library and documented entry point the project uses. Review its actual version and configuration. A generated function named verifySignature may only check that a header exists, compare the wrong value or catch every exception and return true.
Where the team must implement verification itself, route the design through its security review process. Replacing a provider library with a few plausible lines of hashing code introduces a protocol implementation to maintain. A successful unit test using the same custom signing and verification assumptions cannot independently establish that the provider will interoperate with it.
Keep diagnostics useful without exposing signing material. Record the failure category, endpoint configuration reference and relevant request identifier under the logging policy. Do not paste secrets or complete customer payloads into an assistant conversation to troubleshoot a mismatch.
Separate freshness from duplicate handling
In his June 2024 practitioner article, Svix’s Tom Hacohen explains replay protection using signed metadata and highlights the need to authenticate metadata along with the body. This is guidance from a webhook infrastructure vendor, not an independent audit of the fictional application.
A signed request can still be a captured request sent again. Stripe’s webhook documentation describes a signed delivery timestamp, a configurable recency check and a new timestamp and signature for each retry. It warns that setting its tolerance to zero disables the recency check. Do not interpret zero as the strictest possible setting.
Freshness and business duplication nevertheless answer different questions. A recent, authentic retry may refer to an event the application has already processed. Conversely, a recently delivered event may describe an earlier business state. Keep delivery time, event identity and current application state distinct in the design.
Our safe-retry guide addresses repeated effects after uncertain writes. Apply that work after establishing which inbound messages the endpoint accepts. A signature check does not replace duplicate handling, and duplicate handling does not authenticate the sender.
Give the generated handler a rejection matrix
For the fictional course application, the following are proposed review cases. The owner must adapt them to the provider’s real protocol and the application’s access rules.
| Controlled request | Required observation |
|---|---|
| Valid signed event for the intended purchase | Exactly the authorized access change |
| Signature missing or malformed | Rejection with no access change or actionable queued job |
| Body modified after signing | Verification failure before business processing |
| Request signed with another endpoint’s test secret | Rejection under the configured endpoint |
| Authentic delivery outside the configured freshness window | Documented freshness rejection without an effect |
| Authentic repeated event inside that window | No repeated grant or notification beyond the agreed policy |
| Authentic event for a different account or unsupported event type | No unauthorized course access |
Do not stop at response assertions. Inspect the test database, fake queue and notification recorder. An error response after an access grant is a failed boundary even though the HTTP test looks negative. Likewise, returning success for an intentionally ignored event does not necessarily mean the business action ran; assert the actual state.
Run these cases through the application entry point that includes its real middleware configuration. A direct function test can remain useful, but it will not expose a body parser mounted earlier in the request path. Keep test signing keys isolated from production and record the SDK, framework and relevant configuration used.
Retain the business rule after authentication
The final gate belongs to the application. In the fictional example, an authentic event must still map to the intended purchase and account, carry a supported meaning and satisfy the agreed access transition. Do not grant a course merely because an incoming object contains a plausible email address and a success-like status.
Ask the product and integration owner to specify that mapping before accepting generated conditionals. If state can change between inspection and update, the record-update version-check guide covers a further concern. These checks complement authentication rather than expanding what a valid signature proves.
Start with the one handler nearest a consequential business effect. Record the verification boundary, freshness behavior, permitted transition and observed outcomes of the controlled cases. Keep unexecuted checks labeled as proposals. That gives a reviewer something more useful than the assistant’s assurance that the integration is secure.