For a webhook signature verification failure, check the signing secret for that exact endpoint and preserve the original request body. Pass the required headers to the provider’s verifier, then inspect timestamp tolerance and server time. Keep verification enabled throughout. Parsing JSON and serialising it again can change the signed content even when the fields look identical.
An AI response can finish successfully while your application rejects its completion notification. The model has finished, but the event that would continue the workflow has stopped at the receiver. Diagnose that boundary before changing prompts or paying for another generation.
Identify the receiver that rejected the delivery
Take one failed attempt and find the endpoint that actually rejected it. A local forwarding tool can run the same application code as production while using a different signing secret.
Stripe’s signature-error guidance explicitly distinguishes the secret for a CLI-forwarded endpoint from the secret for a Dashboard-managed endpoint. Copying the local secret into production does not connect those identities.
Build a small diagnostic record:
| Evidence | What it resolves |
|---|---|
| Provider endpoint identifier and environment | Whether the failing delivery reached the intended receiver |
| Deployed secret-manager reference and version | Whether that deployment selected the intended signing configuration |
| Verifier error category and receipt time | Whether the failure concerns a mismatch, missing input or freshness rejection |
| Middleware route and body type at verification | Whether the verifier received original text or an already parsed object |
Read configuration through trusted operational tools. Keep secrets and customer payloads out of ordinary logs. A secret-version reference gives an operator something to compare without exposing the key itself.
Preserve the body before middleware changes it
Suppose a provider signs a JSON body containing spaces. Your framework parses it into an object, then the handler calls JSON.stringify() before verification. The new string can omit those spaces. Its fields remain correct while its signed representation has changed.
Adding a raw-body parser inside the handler will not repair a stream already consumed by earlier JSON middleware. Register the webhook route’s provider-appropriate text or raw-body handling before a global JSON parser, or use the framework’s documented original-body capture mechanism.
OpenAI’s Express webhook example uses express.text({ type: "application/json" }) and passes the body and headers to client.webhooks.unwrap(). The helper verifies the signature and returns the parsed event. Follow the API of your installed SDK rather than converting the request into an object first.
Stripe documents body mutation by frameworks and provides specific Next.js and API Gateway guidance. If direct local delivery passes but the deployed path fails, inspect the proxy and serverless mapping as well as application middleware.
For a synthetic request, compare body length and a diagnostic digest at controlled points before verification. A changed digest locates a transformation between those points. Matching digests narrow the investigation; credentials and signing headers still require their own checks. Decide separately whether any production payload may be retained and who may inspect it.
Resolve the provider’s signing context
An API credential authenticates your outbound calls. A signing secret supports verification of incoming events. Choose the credential required by the receiving integration.
Slack’s request-verification documentation uses the app’s Signing Secret. Its OAuth client secret belongs to a different operation. Slack also documents that header names are case-insensitive: code that assumes one spelling can miss a header that reached the server.
Use the provider’s supported verifier for signature interpretation and comparison. Hand-written verification adds another place to mishandle encoding or a supported signature version. When a secret rotates, confirm which version each running deployment uses and apply that provider’s supported transition process.
Test freshness with a fresh request
Slack’s signing example combines a version, timestamp and body, then checks that the timestamp differs from local time by no more than five minutes. That is a Slack-specific documented example, not a universal webhook setting.
A captured request can become too old while you debug it. Replaying it after repairing body handling then produces another legitimate rejection, hiding the repair. A receiver with incorrect system time can also reject a fresh request.
Check clock synchronisation and generate a new signed test through the provider’s supported tooling or a controlled fixture. Preserve freshness validation. Raising the tolerance indefinitely changes the replay protection instead of resolving the underlying fault.
Prove the repair with valid and invalid fixtures
A passing happy-path test establishes only that one request was accepted. The repair also has to retain rejection of requests whose signing inputs no longer match.
Use a non-production endpoint and test secret, through the same middleware and proxy configuration as the failing route. This is a proposed acceptance worksheet, not an executed vendor benchmark:
| Fixture | Required observation |
|---|---|
| Fresh, correctly signed synthetic event | Verification succeeds and the event reaches the intended admission stage |
| Same signed request with one body field changed | Verification fails; no model work or business write starts |
| Request signed with a different test endpoint’s secret | Receiver rejects the request without exposing either secret |
| Required signing header removed | Failure is visible and the event cannot enter processing |
| Out-of-window timestamp, where the provider enforces freshness | Receiver rejects it; a newly signed control still passes |
| Correct event sent through the deployed proxy path | Original signed content and required headers reach the verifier |
Record each fixture’s result against the configuration version. If invalid fixtures reach the worker, the endpoint is still unsafe even when the original delivery error disappears.
Continue the workflow only after admission
Signature verification establishes authenticity under the provider’s signing contract. The application must still check the supported event type and resolve the resource to work it initiated before permitting the next action. A genuine completion event for an unfamiliar job cannot authorise a customer-record update.
For events you intend to process, make durable receipt the acknowledgement boundary and keep substantive work in a worker. OpenAI recommends prompt successful responses and background processing. Acknowledging before saving accepted work creates a loss window if the receiver crashes.
Delivery can also be repeated. Keep event admission distinct from the destination write: the AI agent rollback guide covers idempotent actions and uncertain outcomes. Use the broader integration teardown when the event passes verification but the workflow fails between systems.
Model Operator is a Dubai-based AI product studio, personally led by Alexander Chrisostomou. Its AI Initiative Consulting package includes workflow analysis and readiness engineering. For a blocked AI workflow, bring a redacted delivery error and the endpoint path to a Model Operator build conversation. Establish where legitimate work stops before agreeing what to change.