Inbound Webhooks
Inbound webhooks allow external systems to send events to SolydFlow.
They provide a way for SolydFlow to receive information about events that occur outside of the immediate API request-response flow.
The basic model is:
External System
↓
HTTP Webhook
↓
SolydFlow
↓
Validate
↓
Process Event
↓
Update Transaction / State
Inbound webhooks are particularly important when an external system needs to notify SolydFlow about an event asynchronously.
Why Inbound Webhooks Matter
HTTP API requests are usually request-response operations:
Application
↓
SolydFlow
↓
Response
Webhooks work differently.
The external system initiates the communication:
External System
↓
SolydFlow Webhook Endpoint
This allows SolydFlow to receive events without repeatedly asking the external system whether something changed.
Inbound vs Provider Webhooks
SolydFlow can receive webhook events from different sources.
An important distinction is between:
Inbound Webhooks
A general mechanism for receiving events from external systems.
External System
↓
SolydFlow
Provider Webhooks
Webhook events specifically generated by payment providers.
Payment Provider
↓
SolydFlow
Provider-specific behavior is documented separately.
See:
Basic Webhook Flow
A typical inbound webhook follows this sequence:
External System
↓
HTTP POST
↓
SolydFlow Endpoint
↓
Authenticate / Verify
↓
Validate Payload
↓
Identify Event
↓
Process Event
↓
Persist Result
↓
Return Response
Each stage serves a different purpose.
Webhook Endpoint
A webhook endpoint is an HTTP endpoint exposed by SolydFlow for receiving events.
Conceptually:
POST /webhooks/{endpoint}
The exact endpoint URL and API contract depend on the SolydFlow implementation.
An external system sends its event to the configured endpoint.
External System
↓
POST
↓
SolydFlow Webhook Endpoint
HTTP Method
Webhook integrations generally use an HTTP request to deliver the event.
For event delivery, the payload is typically sent in the request body.
Conceptually:
POST /webhooks/...
Content-Type: application/json
The exact endpoint, headers, and supported methods should follow the webhook configuration for the integration being used.
Webhook Payload
A webhook payload contains information about the event being delivered.
A conceptual payload may contain:
{
"id": "event_123",
"type": "transaction.updated",
"created_at": "2026-08-04T10:00:00Z",
"data": {
"transaction_id": "txn_123"
}
}
The exact payload structure depends on the event source and SolydFlow webhook contract.
Do not assume that all webhook sources use the same payload structure.
Event Type
An event should identify what happened.
For example:
transaction.created
transaction.updated
transaction.completed
These are illustrative event names.
The actual event types supported by a particular SolydFlow integration should be taken from that integration's API documentation.
The event type allows the webhook processor to determine what action is appropriate.
Webhook
↓
Event Type
↓
Event Handler
Event ID
A webhook event should have an identifier where the source provides one.
For example:
event_123
The event identifier is useful for:
- Detecting duplicate deliveries
- Tracking webhook processing
- Debugging failures
- Auditing event history
Conceptually:
Event
└── ID: event_123
Webhook Delivery Is Asynchronous
A webhook is not necessarily delivered at the same time as the original action.
For example:
Payment
↓
External Provider
The webhook may arrive later:
External Provider
↓
...
↓
Webhook
↓
SolydFlow
Therefore, applications and webhook processors should not assume that events will always arrive immediately.
Webhook Delivery Order
Webhook events may not always arrive in the same order in which the underlying actions occurred.
For example:
Event A
Event B
Event C
may arrive as:
Event B
Event A
Event C
A robust webhook processor should therefore use the event's identifiers, timestamps, transaction information, and current system state where appropriate rather than relying solely on arrival order.
The exact ordering guarantees depend on the webhook source.
Duplicate Webhook Delivery
An external system may deliver the same webhook more than once.
For example:
Event A
↓
SolydFlow
↓
Processing
X
Response Lost
The sender may retry:
Event A
↓
SolydFlow
SolydFlow must therefore distinguish:
New Event
from:
Previously Processed Event
This is commonly handled through idempotent event processing.
Idempotent Processing
Webhook processing should be designed so that receiving the same event multiple times does not incorrectly repeat the underlying operation.
Conceptually:
Event A
↓
Process
↓
Stored as Processed
If Event A arrives again:
Event A
↓
Already Processed
↓
Do Not Repeat Side Effect
This is particularly important when an event could affect:
- Transactions
- Entitlements
- Reconciliation
- Notifications
- Other downstream operations
Webhook Acknowledgement
After receiving a webhook, the endpoint should return an appropriate HTTP response according to the webhook contract.
Conceptually:
External System
↓
Webhook
↓
SolydFlow
↓
Process
↓
HTTP Response
A successful acknowledgement tells the sender that the webhook was received according to the integration's delivery contract.
The exact response code and acknowledgement behavior depend on the SolydFlow webhook implementation.
Acknowledgement Does Not Always Mean Business Processing Is Complete
Receiving a webhook and completing every downstream operation are separate concerns.
Conceptually:
Webhook Received
↓
Validate
↓
Accept
↓
Process
For systems that support asynchronous processing, the webhook endpoint may acknowledge receipt while additional processing occurs separately.
For example:
Webhook
↓
Validate
↓
Queue
↓
HTTP 2xx
↓
Worker
↓
Process Event
Whether SolydFlow uses synchronous or asynchronous processing depends on its implementation.
Webhook Verification
Inbound webhooks must be treated as untrusted external input until they have been appropriately verified.
The basic security model is:
Incoming Webhook
↓
Verification
↓
Trusted Event
↓
Processing
Verification can include mechanisms such as:
- Signature verification
- Shared secrets
- Authentication headers
- Timestamp validation
- Event identifiers
The exact mechanism depends on the webhook source.
See:
Never Trust the Payload Alone
A webhook payload should not automatically be treated as authoritative merely because it reached the webhook endpoint.
For example:
HTTP Request
↓
JSON Payload
does not by itself prove:
"The event came from the expected system."
The webhook should first pass the appropriate verification process.
Request
↓
Verify Source
↓
Validate Payload
↓
Process
Payload Validation
After authenticity has been established, the payload should be validated.
Validation should confirm that the event contains the expected structure and required information.
Conceptually:
Webhook
↓
Signature Verification
↓
Schema Validation
↓
Event Processing
For example, a transaction event may require:
event_id
event_type
transaction_id
timestamp
The exact required fields depend on the event contract.
Invalid Webhook Payloads
If the webhook payload does not satisfy the expected schema, it should not be processed as a valid event.
For example:
Webhook
↓
Schema Validation
X
Invalid
The system should record enough information to investigate the failure without unnecessarily storing sensitive payload data.
Unknown Event Types
A webhook endpoint may receive an event type that it does not currently recognize.
For example:
Webhook
↓
event_type = unknown.event
The system should not interpret an unknown event as a known business operation.
Instead, it should handle the event according to the webhook compatibility and versioning strategy.
Possible approaches include:
Unknown Event
↓
Log
↓
Ignore Safely
or:
Unknown Event
↓
Reject According to Contract
The appropriate behavior depends on the webhook contract.
Webhook Event Processing
Once an event has been verified and validated, it can be passed to the appropriate event handler.
Conceptually:
Webhook
↓
Verify
↓
Validate
↓
Identify Event
↓
Handler
For example:
transaction.updated
↓
Transaction Handler
while:
entitlement.updated
↓
Entitlement Handler
The exact event types depend on the SolydFlow webhook system.
Webhook Processing and Transactions
Webhook events can provide information relevant to a transaction.
For example:
Webhook
↓
transaction_id
↓
Find Transaction
↓
Process Event
↓
Update Transaction Evidence
The event should be associated with the correct transaction before changing transaction-related state.
See:
Webhook Processing and Truth
A webhook is evidence that can contribute to determining what happened to a transaction.
The conceptual flow is:
Webhook
↓
Verification
↓
Event Evidence
↓
Truth
↓
Transaction State
The webhook should not necessarily be treated as the final transaction truth by itself.
Multiple sources of evidence may need to be considered.
See:
Webhook Processing and Transaction State
Suppose a webhook indicates that a transaction has changed.
Webhook
↓
Transaction
↓
State Evaluation
The current transaction state should be considered before applying the event.
For example:
Current State:
Successful
Incoming Event:
Pending
The system should not blindly move a trusted transaction backward merely because an older or inconsistent event arrived.
State transitions should follow the transaction-state rules.
See:
Webhook Processing and Finality
Finality provides another important safeguard.
For example:
Transaction
└── Final Successful
An incoming webhook should not automatically invalidate that final decision.
Instead:
Incoming Event
↓
Verify
↓
Validate
↓
Compare With Current State
↓
Truth / Reconciliation
This allows unexpected or conflicting events to be investigated rather than blindly applied.
See:
Webhook Processing and Entitlements
Some events may eventually affect customer entitlements.
The safer model is:
Webhook
↓
Verification
↓
Truth
↓
Transaction State
↓
Finality
↓
Entitlement Enforcement
Not:
Webhook
↓
Grant Access
This distinction prevents an unverified or incomplete event from directly changing customer access.
See:
Webhook Processing and Recovery
Webhook events can help recover transactions whose outcomes are uncertain.
For example:
Payment
↓
Timeout
↓
Unknown
Later:
Provider Webhook
↓
Successful
The webhook provides additional evidence:
Webhook
↓
Verification
↓
Truth
↓
Transaction Resolution
This can allow the transaction to move from an uncertain state toward a final state.
See:
Webhook Processing and Reconciliation
Webhook data can also be compared against other transaction records.
For example:
SolydFlow Transaction
└── Pending
Webhook
└── Successful
This creates evidence that can be evaluated during reconciliation.
Webhook
+
Transaction Record
↓
Reconciliation
↓
Resolved State
See:
Webhook Retries
If a webhook sender does not receive the expected acknowledgement, it may attempt delivery again.
Conceptually:
Webhook
↓
SolydFlow
X
No Expected Response
↓
Retry
↓
SolydFlow
This is another reason webhook handlers must be idempotent.
The same event may arrive multiple times.
Webhook Processing Failures
Webhook processing can fail for several reasons:
- Invalid signature
- Invalid payload
- Unknown event type
- Missing transaction
- Temporary internal failure
- Provider inconsistency
- Processing timeout
These failures should be observable and handled according to the webhook contract.
The goal is to distinguish:
Invalid Event
from:
Valid Event
└── Temporary Processing Failure
These situations may require different responses.
Temporary vs Permanent Failure
A webhook processing failure may be temporary.
For example:
Webhook
↓
Database Temporarily Unavailable
The event may be safe to retry.
Another failure may be permanent:
Webhook
↓
Invalid Signature
Retrying the same invalid event may not solve the problem.
Therefore, webhook processing should classify failures appropriately.
Webhook Observability
Webhook processing should be observable.
Useful information can include:
Event ID
Event Type
Received At
Source
Processing Status
Processing Duration
Transaction ID
Failure Reason
For example:
Event:
event_123
Type:
transaction.updated
Transaction:
txn_456
Status:
Processed
This makes webhook-related incidents easier to investigate.
Webhook Audit Trail
A webhook event may become important when investigating a transaction.
A useful history might look like:
Transaction TX-123
10:01 Payment Created
10:02 Provider Request
10:03 Timeout
10:05 Webhook Received
10:05 Webhook Verified
10:05 Transaction Updated
10:05 Finality Evaluated
This provides an operational trail connecting external events to internal transaction decisions.
Webhook Security
Webhook endpoints are externally reachable interfaces and should therefore be treated as security-sensitive.
Important considerations include:
- Signature verification
- Credential protection
- Replay protection
- Input validation
- HTTPS
- Rate limiting where appropriate
- Safe logging
- Least-privilege processing
See:
Replay Protection
An attacker or external system could potentially send the same valid webhook repeatedly.
Therefore, a secure webhook system should consider:
Event ID
+
Timestamp
+
Signature
when determining whether a request is a legitimate new delivery.
The exact replay-protection mechanism depends on the webhook source.
Sensitive Data in Webhook Logs
Webhook payloads may contain sensitive information.
Logging should therefore avoid unnecessarily storing:
- Payment credentials
- Authentication secrets
- API keys
- Personal information that is not required for debugging
- Complete raw payloads when they are not necessary
Prefer storing the minimum information needed for:
- Debugging
- Auditability
- Event correlation
- Operational investigation
See:
Webhook Versioning
Webhook payloads can evolve over time.
A robust webhook system should make it possible to distinguish between supported versions where versioning is part of the integration contract.
Conceptually:
Webhook
↓
Version
↓
Compatible Handler
This prevents a change to an event schema from unexpectedly breaking existing integrations.
The exact versioning strategy depends on the SolydFlow API.
Webhook Event Lifecycle
A useful model for an inbound event is:
Received
↓
Verified
↓
Validated
↓
Identified
↓
Processed
↓
Recorded
If verification fails:
Received
↓
Verification Failed
↓
Rejected
If processing temporarily fails:
Validated
↓
Processing Failed
↓
Retry / Recovery
Example: Valid Webhook
An external system sends:
POST /webhooks/example
with an event:
transaction.updated
The processing flow is:
Webhook
↓
Verify Signature
↓
Validate Payload
↓
Identify Event
↓
Find Transaction
↓
Process Evidence
↓
Truth
↓
Transaction State
If the resulting state is final:
Transaction State
↓
Finality
↓
Enforcement
Example: Duplicate Webhook
The same event arrives twice.
First delivery:
event_123
↓
Process
↓
Store Event ID
Second delivery:
event_123
↓
Event Already Processed
↓
Do Not Repeat Side Effect
The webhook can therefore remain safe under repeated delivery.
Example: Invalid Signature
An event arrives:
Webhook
↓
Signature Verification
X
Invalid
The event should not proceed to transaction processing.
Invalid Signature
↓
Reject
↓
Record Security Event
See:
Example: Unknown Transaction
A valid webhook references a transaction that SolydFlow cannot currently locate.
Webhook
↓
Verified
↓
Transaction ID
↓
Transaction Not Found
The system should not invent a transaction state.
Depending on the integration contract, the event may need to be retried, queued, investigated, or rejected.
The correct behavior depends on the SolydFlow implementation.
Example: Webhook Arrives After Recovery
A transaction times out:
Payment
↓
Timeout
↓
Recovery
Recovery begins investigating the transaction.
Later:
Webhook
↓
Successful
The new evidence can be incorporated:
Recovery
+
Webhook Evidence
↓
Truth
↓
Transaction State
↓
Finality
This demonstrates why webhook processing and recovery must work together.
Example: Out-of-Order Events
Suppose the system receives:
transaction.completed
before:
transaction.processing
The processor should not blindly apply events based solely on arrival order.
Instead:
Event
↓
Transaction
↓
Current State
↓
Event Timestamp / Sequence
↓
State Rules
↓
Apply or Investigate
The exact ordering guarantees depend on the event source.
Designing a Reliable Webhook Consumer
A reliable webhook consumer should aim to be:
Authentic
Only accept events that pass the required verification.
Idempotent
Repeated events should not create repeated side effects.
Validated
Do not process malformed payloads.
Observable
Make event processing easy to investigate.
Resilient
Handle temporary failures without losing events.
State-aware
Consider the current transaction state before applying an event.
Secure
Protect secrets and sensitive information.
Webhook Processing Model
The complete model is:
External System
↓
Webhook
↓
Receive
↓
Verify
↓
Validate
↓
Identify
↓
Deduplicate
↓
Process
↓
Truth / Transaction State
↓
Finality
↓
Enforcement
This creates a controlled path from an external event to a revenue decision.
Key Principles
1. Treat webhooks as external input
Do not trust an incoming request merely because it reached the endpoint.
2. Verify before processing
Authenticate the source before using the event as transaction evidence.
3. Validate the payload
Ensure the event conforms to the expected contract.
4. Make processing idempotent
The same event may be delivered more than once.
5. Do not assume delivery order
Events may arrive late or out of order unless the source guarantees ordering.
6. Do not confuse evidence with truth
A webhook can contribute evidence without automatically becoming the final transaction state.
7. Do not grant entitlements directly from webhooks
Use the Truth → Finality → Enforce flow.
8. Make failures observable
Webhook problems should be easy to identify and investigate.
9. Protect sensitive information
Webhook payloads and credentials should be handled securely.
10. Preserve event history
Event IDs and processing history make duplicate detection and debugging significantly easier.
The Core Principle
An inbound webhook is an external event entering SolydFlow; it becomes useful to the revenue system only after it has been verified, validated, and correctly associated with the relevant state.
The simplified flow is:
External Event
↓
Webhook
↓
Verify
↓
Validate
↓
Process
↓
Truth
↓
Finality
↓
Enforce