Replies: 2 comments 4 replies
-
Most fintech companies widely adopt the Sync-to-Async trigger pattern, where third-party APIs provide an immediate acknowledgment response upon receiving a request, but the actual processing is completed asynchronously. The final status or result is communicated later via a callback to a webhook endpoint. This pattern is especially common in the payments and transaction processing domains, where real-time acknowledgments are crucial for user experience, but backend processing may involve delays due to settlement, validation, or third-party dependencies. 📌 Example: The payment gateway immediately responds with:
After processing (which could take seconds or minutes), the gateway sends an HTTP POST callback to the client’s webhook:
This asynchronous update mechanism is a critical requirement across the fintech industry and is heavily used in UPI, BBPS, card processing, loan disbursals, and KYC verification workflows. |
Beta Was this translation helpful? Give feedback.
-
Yes, my top priority is supporting OpenAPI Callbacks, as that directly enables mocking the Sync-to-Async flows we rely on in payment and onboarding scenarios — where we receive an immediate acknowledgment and later get asynchronous status updates via webhooks. Also, support for x-microcks: trigger would be super valuable, as it would give us fine control over when and how callbacks are fired during mocks, making the simulations much closer to real-world scenarios. The OpenAPI triggering AsyncAPI publication would be great to have down the line, but for now, my primary focus is on the Callbacks pattern. I’d be happy to champion this — I can actively test, review, and provide feedback to ensure the feature is robust and solves real-world problems. |
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
-
Hey Microcks community!
As we're starting a new year and a new development cycle, I'd like to share and discuss the design ideas I have around 3 related topics:
These elements were on our roadmap for a long time (Roadmap), and I saw some demands recently on those topics. As these topics are closely related, I spent some time thinking about the best way to add support and implementation in Microcks.
Please consider this discussion as an opportunity to comment and share what you'd like to see and your feelings about the proposed plan. Feel free to react to anything and propose an alternative approach if it sounds better to you!
I'll expose here my analysis on 3 different topics and then different options I have considered for representation and implementation.
References:
Analysis
Callbacks are defined with both request (from API owner to user) and response (from user server to API owner)
Callbacks unsubscribe method is not defined by the spec. It’s up to the implementation to provide an
/unsubscribe
operation and a subscription identification mechanism (based on id or whatever)Webhooks - even if closely related to the callbacks feature - describe requests initiated other than by an API call, for example, by an out-of-band registration. We can typically think here about the webhooks that can be registered via the GitHub administration console and allow third-party apps to receive HTTP notification for events (whatever the entity)
It's a very common pattern to have a synchronous interaction (ie. invocation of Rest/Soap/Graph/Grpc API operation) triggering the publication of an asynchronous event on a channel (and thus an AsyncAPI subscribe operation). So why not be able to define this triggering from the mocking step in API lifecycle?
Example cases
These are simplified representations with some levels of complexity ignored to make things simple to understand.
Callback
Webhook
Sync-to-Async triggers
Model representation
Option 1 for callbacks
Callbacks are defined as other pairs of
Request
/Response
attached to the same operation and related to the origin example.In that case, we need a new discriminator (or type of request and response) to tell Microcks it’s a callback-related request or response.
Operation
POST /subscribe
=> 1 Request and 1 Response withoperationId
pointing to operation => 2 Requests (and 2 Responses) of typeCallback
with the reference of the event in the Spec + the endpoint expression ({$request.body#/callbackUrl}
)Option 2 for callbacks
Callbacks are defined as additional
EventMessage
s attached to the same operation and related to the origin example.EventMessage
already holds adispatchCriteria
that can be used to hold the endpoint expression ({$request.body#/callbackUrl}
). We would need an additional property to keep track of event name (createEvent
orupdateEvent
) for the sake of completeness.Option 1 for webhooks
We can ignore them and simply argue that people have to consider AsyncAPI instead 😉
Option 2 for webhooks
Webhooks are defined similarly to AsyncAPI using
EventMessage
s attached to an operation bound to aREST API
in Microcks. In that case, the REST API may have a traditional HTTP-Verb operation +SUBSCRIBE
like operation in AsyncAPI (meaning that the consumer will receive events)Options for Sync-to-Async triggers
Mapping onto Microck’s internal model is obvious as we have 2 different APIs with already existing
Request
/Response
/EventMessage
types that can live independently. One thing we should add though is this concept oftrigger
:Supporting both side’s specifications -
trigger
andtriggerBy
- can be tricky, and it may lead to inconsistencies. Things would be easier just supporting the OpenAPI side of things withtrigger
(it would also not trigger an update of unrelated API). The 2nd option seems more natural as it’s where the business logic of event triggering should be located.Runtime implementation
Option 1 for callbacks
Implement sending back requests in the main web app component. We may use Spring internal
ApplicationEvents
to have temporal decoupling with the main mock invocation thread (like we’re already doing formetrics
gathering or event publication to async-minion). We need a way to wait for a specified (short-)time before sending the event without locking threads or resources (see concern#2
below)It fits whatever option is used for modeling.
Option 2 for callbacks
Implement sending back requests in the async-minion component. It fits whatever option is used for modeling, but it adds a hard dependency on async stuff, even for « simple » OpenAPI use cases. Here again, we need a way to wait for a specified (short-)time before sending the event without locking threads or resources (see concern
#2
below). The scheduler we used on Quarkus is much more appropriate for long-running tasks, not for ephemeral and short-lived notifications.Option 1 for webhooks
Implement sending back requests in the main web app component. As we just have a basic scheduler on the main component (just for import jobs), this would require duplicating the scheduling and long-running task logic we already have in the async-minion…
Option 2 for webhooks
Implement sending back requests in the async-minion component.
This option fits better with the modeling option 2 for webhooks as we can solely rely on the
EventMessage
definitions to send stream of messages. The process would be as follows:EventMessage
definitions#4
below), attach AsyncAPI and webhooks via the sameAsyncMockDefinition
#3
below):Options for Sync-to-Async triggers
Implementation of sending triggered event must be realized in the async-minion component. Triggering command will be materialized as an event sent from the Microcks main component to the async-minion (via Kafka or WebSocket for the uber images) and message reception (filtered by minion-supported bindings) will trigger a single message publication.
ProducerManager
will need refactoring to allow the reuse of single message publication outside of the scheduled jobs.How do we reuse content from the incoming request into our triggered event messages? See concern
#1
below.Concerns
{{request.body/path}}
) seem to fit well here. In the context of AsyncAPI triggering, we may use the presence of{{ (request|response).* }}
expression as a filter to know that we should use this as a template for sending messages. These same messages would be ignored for regular AsyncAPI mock events publication.createEvent
must be sent back beforeupdateEvent
but Microcks can’t guess this based on event names).x-microcks/frequency
property at the operation/webhook level.Summary
Proposed priorities:
Proposed options:
trigger
custom property support only, as a multi-valued propertyBeta Was this translation helpful? Give feedback.
All reactions