Handle a Payment Webhook Safely

From the team behind aidrop.it — one workspace to build, host, and keep changing your code.

Handle a payment webhook by verifying the provider's signature, recording the event in durable storage and making the payment action safe to repeat. Expect duplicate deliveries and events arriving out of order. Acknowledge accepted work after saving it, then track processing so a deployment cannot erase the obligation to update the order.

A customer pays, closes the browser and never reaches your success page. Your backend still needs to confirm the payment. The provider sends a webhook to your server for that purpose. The order retry contract prevents repeated purchase requests; webhook handling covers the later confirmation from the payment system.

Verify the sender

Verify each webhook with the provider's official library, the signature header and the signing secret for that endpoint. Preserve the raw request body until verification finishes. After the check succeeds, identify the provider account, environment and order that the event belongs to before changing a customer's purchase record. Select the event types your payment flow needs.

Stripe's signature verification guide explains why parsing and rebuilding JSON can break the check. Use the secret for the registered endpoint; the local CLI listener has its own secret. Keep these values in server-side configuration. Check the payment reference, amount and currency against the order before marking it paid.

Record the event

Record a verified event with a unique key scoped to the provider account, environment and event ID. Commit the event and its pending processing record together before returning success. If saving fails, return a failure so the provider can retry. A response followed by a process crash must leave work that another attempt can resume.

Stripe documents retries and duplicate delivery. Acknowledge an event already in durable storage without creating another pending task. Enforce uniqueness in the database so concurrent deliveries cannot both create work. Keep processing status separate from receipt status and monitor stalled tasks.

Use the background-job recovery drill for the worker. Recording an event ID before its business action, then skipping it forever, can strand an accepted payment. Resume pending work and coordinate the order update with its completion record.

Guard fulfillment

Prevent repeated fulfillment at the order or payment boundary as well as at the event boundary. A provider may emit different event IDs about one purchase and deliver an older event after a newer one. Use an explicit order state transition and reconcile uncertain payment status through the provider's API before shipping goods or granting access.

Stripe's fulfillment guidance calls for handling repeated and concurrent fulfillment calls. Commit the paid state and any pending fulfillment task together. For external effects, preserve a stable operation key or a reconciliation step; an event-ID check alone cannot prevent two shipments.

Keep evidence in the operating record: event ID, payment reference, order transition and processing result. Exclude card data and signing secrets. A delivery marked successful in the provider dashboard proves acknowledgment; check the order to prove fulfillment.

Webhook check

Run this check in the provider's test environment with a disposable order and fulfillment destination. Send the same event twice, overlap two deliveries and interrupt processing after acknowledgment. Check the event record and order together. Record which work completed, which work can resume and how you resolve an uncertain external effect.

PAYMENT WEBHOOK CHECK
Public HTTPS endpoint and subscribed event types:
Signature library and endpoint-secret name:
Account/environment/event uniqueness constraint:
Payment reference, amount and currency checks:
Pending-work record and reconciliation owner:

[ ] Invalid signature changes no order
[ ] Failed durable write returns a failure response
[ ] Duplicate and concurrent deliveries keep one task
[ ] Restart after acknowledgment resumes pending work
[ ] Different events for one payment fulfill one order
[ ] Delayed older event cannot undo a settled transition
[ ] Dashboard delivery and order result agree

FAQ

Can the success page mark an order paid? Treat the browser redirect as a customer-facing status page. Have the server confirm payment through verified provider information. A customer can close the browser before redirecting, and a visitor can request a success-page URL without paying.

Does returning HTTP 200 finish the payment work? It acknowledges delivery to the webhook endpoint. Your application still needs durable processing and a record of the order update. Return success after accepting the work into storage, then check that the worker completes it.

Can I receive payment webhooks on aidrop.it? Your application can expose a webhook route at its public HTTPS address on aidrop.it. Configure the provider's endpoint secret as a Project secret and name it in the Service's required_secret_names. Your code owns signature verification, deduplication and payment reconciliation.