Stripe webhook verification: from event delivery to order updates

Know which event contract you are implementing

List the events your application needs and the business transition each may trigger. Avoid subscribing to a large set of events and treating all of them as evidence that an order is paid. Record whether the endpoint is receiving provider events directly or notifications from an orchestration layer. Those are separate contracts with their own identifiers and verification rules. In a shop selling a digital service, one event may confirm payment while another merely reports a change requiring investigation. The event name should lead to an explicit decision, not a broad assumption.

Payment webhooks

Verify before trusting the payload

Follow the sender's documented signature procedure, including the required request representation and secret handling. Stripe's guidance should be used for Stripe events; Adyen documents its own webhook handling approach. Keep verification secrets out of browser code, public repositories and routine logs. Decide how invalid or unverifiable requests are recorded without letting their contents drive order changes. A useful operational record states that verification failed, which endpoint was involved and when it happened. It does not need to reproduce sensitive payload fields to make the failure visible to the team.

Developer tools

Accept delivery without losing the business task

Separate endpoint acknowledgement from lengthy downstream work. Your design should durably record or queue the verified event before confirming receipt according to the sender's contract. If processing later fails, the system needs a way to retry that business task without depending on a new customer action. Do not return a success response while silently dropping an event that was never stored. Equally, avoid repeating a charge or shipment simply because an unrelated downstream notification service is unavailable. Document the boundary between transport receipt and completion of the internal workflow.

Expect duplicates and out-of-order information

A delivery mechanism may retry, and different events may not reach your application in the order a human expects. Use event identifiers and controlled order transitions to make repeated processing harmless. Before applying an update, check whether it is consistent with the state already known. If necessary, retrieve the current payment through the supported API rather than relying only on an older event snapshot. For example, a late pending update should not blindly replace a confirmed payment state. Keep the original event available for investigation while applying the application's current-state rules.

• Deduplicate the event before a fulfilment side effect.
• Keep order and provider identifiers searchable.
• Record the processing outcome separately from delivery receipt.
• Make rejected transitions visible rather than silently rewriting history.

Practise recovery with operational staff

Test a delivery while the endpoint is unavailable, then inspect the recovery path described by the sender. Test an invalid signature, a repeated event and a valid event whose order reference cannot be found. Give each failure a clear owner. The support team should be able to distinguish an unpaid order from a paid order whose internal update is delayed. Recovery should use the event journal, payment status and order record together. Replaying a message is an operational action with possible side effects, so it should follow the same safeguards as the original delivery.

Keep provider and OrsunPay verification separate

OrsunPay offers signed payment notifications and delivery investigation tools, subject to permissions and the supported deployment. An application consuming OrsunPay events must verify the OrsunPay contract rather than applying a Stripe signing procedure to a different sender. The PSP remains responsible for settlement, and a successful webhook delivery is not a settlement record. Establish the notification source, the trusted verification method and the authorised business action at each boundary. That separation makes it possible to operate several provider connections without confusing who reported an event or what the report proves.

Sources

• Stripe — Webhooks
• Adyen — Webhooks