Webhooks
Webhooks allow systems to communicate asynchronously when something happens.
In payment infrastructure, this is especially important because a payment can change state after the original payment request has already completed.
For example:
Payment Request
↓
Payment Provider
↓
Transaction Processed
↓
Webhook
↓
SolydFlow
The webhook allows SolydFlow to receive information about the transaction without continuously asking the provider whether something has changed.
Why Webhooks Matter
A payment does not always finish within the lifetime of the original request.
For example:
Application
↓
Payment Request
↓
Provider
↓
Pending
Later, the provider may complete the transaction:
Provider
↓
Payment Successful
↓
Webhook
The webhook allows the application or SolydFlow to learn about that change asynchronously.
Webhooks in SolydFlow
SolydFlow sits between your application and multiple payment systems.
A simplified flow is:
Your Application
│
▼
SolydFlow
/ \
▼ ▼
Paystack Flutterwave
│ │
└────┬─────┘
│
Webhooks
│
▼
SolydFlow
│
▼
Transaction State
The exact provider and integration behavior depends on the payment provider.
Two Directions of Webhooks
Within the SolydFlow ecosystem, it is useful to distinguish between two directions of webhook communication.
Provider Webhooks
A payment provider sends an event to SolydFlow.
Payment Provider
↓
Provider Webhook
↓
SolydFlow
For example:
Paystack
↓
Payment Successful
↓
Webhook
↓
SolydFlow
Provider webhooks allow SolydFlow to receive asynchronous information about transactions.
See:
Inbound Webhooks
Inbound webhooks are webhook endpoints exposed by SolydFlow for receiving events.
Conceptually:
External System
↓
SolydFlow Webhook Endpoint
↓
Event Processing
The exact source and purpose depend on the integration.
See:
Webhooks and Transactions
Webhooks can provide evidence that affects a transaction's state.
For example:
Transaction
└── Pending
Webhook
└── Successful
SolydFlow can process the webhook and use the event as part of its transaction state resolution.
Webhook
↓
Validate
↓
Identify Transaction
↓
Process Event
↓
Update / Evaluate State
A webhook is therefore an important input into the transaction lifecycle.
A Webhook Is Evidence
A webhook should not automatically be treated as unquestionable transaction truth.
For example:
Webhook
└── Successful
The system should still establish that:
- The event came from the expected source
- The event is authentic
- It belongs to the expected transaction
- The event has not already been processed
- The event is compatible with the transaction lifecycle
This is why webhook handling works together with SolydFlow Truth.
Webhook
↓
Validation
↓
Transaction
↓
Consensus / Truth
↓
Transaction State
Webhooks and Truth
Webhooks are one source of transaction evidence.
The Truth layer can combine webhook information with other available evidence.
Provider Response
│
Webhook│
│
Verification
│
Recovery
▼
Consensus
↓
Transaction State
This is especially important when webhook information is missing, delayed, duplicated, or inconsistent with another source.
See:
Webhooks and Recovery
A webhook may fail to arrive.
For example:
Provider
↓
Successful
X
Webhook
SolydFlow may therefore continue to show:
Pending
Recovery can identify the unresolved transaction and use verification or other mechanisms to establish its state.
Pending
↓
Webhook Missing
↓
Recovery
↓
Verification
↓
Successful
This is one of the reasons SolydFlow does not rely exclusively on webhooks for transaction truth.
See:
Webhooks and Transaction History
Webhook events can become part of the transaction history.
For example:
Created
↓
Pending
↓
Provider Webhook
↓
Successful
The transaction ledger can preserve the relevant event and state transition.
See:
Webhooks and Event Handling
Receiving a webhook is only the beginning.
A reliable webhook flow is:
Receive
↓
Authenticate / Verify
↓
Parse
↓
Identify Event
↓
Identify Transaction
↓
Check Duplicate
↓
Process
↓
Update State / Record Event
This prevents a webhook from being treated as a simple HTTP request with no transaction context.
See:
Webhook Signatures
Payment providers commonly provide mechanisms for verifying that webhook requests originated from the expected source.
Conceptually:
Webhook Request
↓
Signature
↓
Verification
↓
Trusted Event
SolydFlow should validate provider-specific webhook signatures according to the requirements of each integration.
See:
Why Signature Verification Matters
Without appropriate verification, an application could potentially accept an event that did not originate from the expected provider.
For example:
Untrusted Request
↓
"Payment Successful"
↓
Application
That could result in an incorrect transaction state or entitlement.
A safer flow is:
Webhook
↓
Signature Verification
↓
Valid?
/ \
No Yes
↓ ↓
Reject Process
The exact verification mechanism depends on the provider.
Webhooks Can Arrive More Than Once
Webhook systems should be designed with duplicate delivery in mind.
For example:
Webhook A
Webhook A
Webhook A
These may all represent the same underlying event.
The system should not interpret them as:
Payment A
Payment B
Payment C
Instead:
One Event
↑
Multiple Deliveries
This is why idempotent event handling is important.
See:
Webhooks Can Arrive Late
A provider webhook may arrive after SolydFlow has already resolved a transaction through another mechanism.
For example:
Payment
↓
Pending
↓
Verification
↓
Successful
Later:
Provider Webhook
└── Successful
The webhook should be processed against the existing transaction rather than creating a new payment or reversing the established state.
Webhooks Can Arrive Out of Order
Consider:
Generated:
A → B → C
but:
Received:
B → A → C
Event processing should therefore account for transaction history and event meaning rather than assuming that arrival order is transaction order.
This is particularly important when multiple events can affect the same transaction.
Webhooks and Transaction States
A webhook may cause or contribute to a state transition.
For example:
Pending
↓
Successful Webhook
↓
Successful
But a webhook does not necessarily mean that every transaction should immediately move to a final state.
For example:
Pending
↓
Pending Webhook
↓
Pending
The resulting state depends on the event and the transaction lifecycle.
See:
Webhooks and State Mismatches
A webhook can reveal a difference between provider and SolydFlow state.
For example:
SolydFlow
└── Pending
Provider Webhook
└── Successful
This creates a state mismatch that can be evaluated by the Truth layer.
Webhook
↓
Mismatch Detected
↓
Evidence Evaluation
↓
Consensus
↓
Resolved State
See:
Webhooks and Reconciliation
Webhooks provide real-time or near-real-time information, while reconciliation can provide a broader mechanism for checking whether transaction records agree.
Webhook
↓
Real-Time Event
Reconciliation
↓
Record Comparison
They complement each other.
A webhook may update a transaction immediately, while reconciliation can later detect transactions for which expected events were missing or incorrectly processed.
See:
Webhook Processing Should Be Idempotent
A webhook handler should be able to safely process the same event more than once.
Conceptually:
Event A
↓
Process
↓
Transaction Updated
Event A
↓
Process Again
↓
No Duplicate Effect
This is especially important because network failures can cause senders to retry webhook delivery.
Webhook Processing Should Be Observable
Webhook processing should provide enough information to determine what happened when an event is received.
Useful operational information can include:
- Event received
- Event source
- Event identifier
- Associated transaction
- Verification result
- Processing result
- Processing error
- Retry information
- Timestamp
This makes webhook failures easier to investigate.
Webhook Failures
A webhook can fail at several stages:
Provider
↓
Delivery
↓
Endpoint
↓
Authentication
↓
Parsing
↓
Transaction Matching
↓
Processing
A failure anywhere in this chain can prevent the transaction event from being processed correctly.
This is why SolydFlow treats webhook handling as a complete workflow rather than simply exposing an endpoint.
Webhook Security
Webhook endpoints are externally reachable integration points and should be protected appropriately.
Important considerations include:
- Signature verification
- HTTPS
- Request validation
- Event validation
- Transaction validation
- Replay protection where supported
- Idempotent processing
- Secure credential handling
- Logging without exposing sensitive information
See:
Webhooks and Provider Integrations
Each provider may have different webhook behavior.
For example, providers may differ in:
- Event names
- Payload structures
- Signature mechanisms
- Retry behavior
- Transaction identifiers
- Status values
- Event ordering
- Delivery behavior
SolydFlow abstracts these provider-specific differences into its unified transaction model where supported.
Paystack Webhook
│
Flutterwave Webhook
│
Stripe Webhook
│
▼
Provider Adapter
↓
SolydFlow Event Model
↓
Transaction
Provider-specific details belong in the provider documentation.
See:
Webhooks and the SolydFlow Model
A simplified SolydFlow webhook flow is:
Provider
↓
Webhook
↓
SolydFlow Endpoint
↓
Verify
↓
Normalize
↓
Identify Transaction
↓
Process Event
↓
Truth / Transaction State
↓
Ledger
This allows different providers to communicate transaction events through a consistent infrastructure layer.
What Happens When a Webhook Is Not Enough?
Sometimes the webhook does not provide enough information to determine the correct transaction state.
For example:
Webhook
└── Unknown / Incomplete
Transaction
└── Pending
The system may need additional evidence.
Webhook
↓
Insufficient Evidence
↓
Verification
↓
Consensus
↓
Transaction State
This is where Webhooks connects directly with Truth and Recovery.
A Complete Webhook Example
Consider a customer making a payment.
1. Payment begins
Customer
↓
Application
↓
SolydFlow
2. SolydFlow sends the payment to a provider
SolydFlow
↓
Payment Provider
3. Provider processes the payment
Provider
└── Successful
4. Provider sends a webhook
Provider
↓
Webhook
↓
SolydFlow
5. SolydFlow validates the event
Webhook
↓
Signature Verification
↓
Transaction Matching
6. Event is processed
Webhook
↓
Event Handling
↓
Transaction
7. Transaction state is resolved
Evidence
↓
Truth
↓
Successful
8. Transaction history is recorded
Transaction Ledger
└── Successful
Webhook Design Principles
1. Treat webhooks as asynchronous events
Do not assume the webhook will arrive immediately.
2. Verify incoming events
Do not trust external events without appropriate validation.
3. Make processing idempotent
Repeated delivery should not create repeated side effects.
4. Expect delays
A valid webhook may arrive later than expected.
5. Expect duplicates
Providers may retry delivery.
6. Expect out-of-order events
Event arrival order may differ from generation order.
7. Connect events to transactions
Every event should be associated with the correct transaction where possible.
8. Do not rely exclusively on webhooks
Recovery, verification, and reconciliation provide additional mechanisms for dealing with missing or inconsistent events.
9. Preserve event history
Webhook activity should remain traceable when it affects transaction processing.
10. Keep provider differences isolated
Provider-specific webhook formats should be handled within the provider integration layer rather than forcing every application to understand them.
The Core Principle
Webhooks provide asynchronous payment events; SolydFlow turns those events into reliable transaction processing through validation, event handling, Truth, recovery, and reconciliation.
The simplified model is:
Provider
↓
Webhook
↓
Validation
↓
Event Handling
↓
Transaction
↓
Truth
↓
Ledger
When the webhook is missing or insufficient:
Webhook Missing / Insufficient
↓
Recovery
↓
Verification
↓
Consensus
↓
Transaction State