A fulfillment app receives a request claiming that a shipment has been dispatched. Its JSON has the expected fields, so the application updates the order. That structure proves only that someone knew the format. Webhook signature verification establishes whether a message matches the provider's authentication contract before its contents can influence business state.

For a fictional bicycle-delivery service, incoming shipment notifications can change what customers see and what staff do next. Verification belongs at the receiving boundary, before the event is treated as an authorized update. It remains separate from deciding whether the update is valid for the current order state.

Verify the bytes the provider signed

Use the provider's supported verification library and endpoint-specific configuration. Many signature schemes authenticate the raw request body. Parsing JSON and serializing it again can change whitespace or encoding and produce different bytes, even when the interpreted object looks identical.

Stripe's webhook endpoint guidance documents signature troubleshooting and the importance of the original body for its verification process. Other providers can use different schemes. Follow the selected provider's exact contract rather than assuming one header format works for every integration.

Configure middleware order deliberately. The route may need access to raw bytes before a general body parser consumes them. Set sensible request limits and reject malformed authentication information without logging secrets. A successful local test does not confirm that a deployed proxy or framework preserves the same input.

Keep secrets scoped to the endpoint

Distinguish test and production secrets and keep them in the appropriate server-side configuration. A delivery-service sandbox should not authorize production order changes. Avoid using a developer's local forwarding secret as though it were the deployed endpoint's secret.

Plan rotation using the provider's supported overlap behavior where available. The team should know which versions are accepted, when an old secret stops working and how failed verification is monitored during the change. Copying a new secret into one instance while others retain the old configuration can produce intermittent failures.

Verification errors need a useful operational signal. Record a safe reason category, endpoint identity and correlation context. Do not preserve full sensitive payloads by default merely because they would make debugging convenient. Give staff a controlled route to inspect provider delivery records when necessary.

Separate freshness, duplication and business order

A valid signature does not necessarily mean a message is new. Use the provider's supported timestamp and tolerance checks for freshness, with appropriate clock handling. A timestamp check alone does not prevent repeated processing inside its accepted interval.

Keep a durable event identifier and a repeat-processing rule. The same authenticated notification may be delivered again during normal retries. For the bicycle service, another delivery should find the existing handling result instead of generating another dispatch action or customer notice.

Also consider out-of-order events. Authentication answers who supplied the message under the scheme; it does not decide whether an earlier shipment state should replace a later one. Check the current order and the provider's sequencing or retrieval contract before applying a transition.

Acknowledge after the event is safely accepted

If processing is asynchronous, establish a durable accepted record before returning the success response used by the provider. A request acknowledged before it is stored can disappear during a crash. The worker should retain the verification outcome and trusted event identity with the accepted work.

Test a valid signed request, altered bytes, an incorrect endpoint secret, an expired timestamp and duplicate delivery in a safe environment. During integration development, verify the deployed middleware path as well as the helper function. The receiving boundary succeeds when an authentic message is preserved reliably and every subsequent state change still follows the application's business rules.