FluidRWA Learn
How to Design Reliable Payment Webhook Processing
What you will do
A webhook reports an event; it is not automatically proof that a beneficiary received spendable funds. Provider event types, signature schemes and retry rules differ.
Before you start
The payment provider's current webhook and API documentation, a test environment and an agreed payment-state model.
Step 1: Map the payment states
List the provider's documented events from order creation through funding, conversion, payout and completion. Identify which event means an on-chain transfer versus final beneficiary delivery.
Step 2: Register a secure endpoint
Use HTTPS and store signing secrets in a secret manager. Follow the provider's exact signature procedure, including its rules for raw request bytes and timestamp checks where supported.
Step 3: Verify before processing
Reject unauthenticated requests according to provider guidance. Do not trust fields in an unverified payload or log signing secrets and unnecessary personal data.
Step 4: Make processing idempotent
Store stable provider event and order identifiers. Make duplicate deliveries safe, and acknowledge events according to the provider's delivery contract after durable receipt.
Step 5: Handle ordering and retries
Events may arrive late or out of order. Use the provider's API and documented state transitions to reconcile the latest valid state; do not blindly overwrite a later state with an earlier notification.
Step 6: Reconcile the payment outcome
Match provider IDs, transaction hashes, fees and payout references against your ledger. Give operations staff a queue for missing, mismatched or delayed events.
Step 7: Test failure and rotation
Exercise duplicate, delayed, invalid-signature and missing events in a sandbox. Test secret rotation, alerting and replay procedures using the provider's documented capabilities.
Check your work
A duplicate event cannot create a duplicate payout, and a missing or invalid event is visible to operations.
FAQs
Does a webhook prove a payment settled?
Only the provider's documented event meaning and your reconciliation can establish the relevant outcome.
Are all webhook signature schemes identical?
No. Follow the specific provider's documentation and validate its current implementation.