Should the VC API support callbacks?

[msporny]

There are times where it might be appropriate for the VC API to use callbacks. Two use cases are:

1. Report to an external system on progress, such as the issuance of a VC.
2. Retrieve data from an external system to use in an exchange.

Consider the following diagram:

sequenceDiagram
    participant WS as Wallet Service
    participant IA as Issuer App (Business Logic)
    participant PS as Presentation Service
    participant IS as Issuer Service
    autonumber
    WS->>PS: Request VC (VC-API)
    PS->>WS: Request authentication (VC-API + VPR)
    WS->>PS: Provide authentication (VC-API + VP)
    PS->>IA: Retrieve data needed for VC
    PS->>IS: Issue VC (VC-API)
    IS->>PS: Issued VC (VC-API)
    IS->>IA: VC has been issued (VC-API)
    PS->>WS: Issued VC (VC-API + VP)
    PS->>IA: Exchange has been completed (VC-API)

Loading

Steps 4, 7, and 9 are callbacks that might be useful for the services defined by the VC API. Thoughts?

[jrhender]

I think this is a good approach to allow for generic Presentation Services/Issuer Services to be used with other apps that have business logic. That said, I'm not sure that such callbacks are in the scope of VC-API or if they are features that a specific VC-API implementation could offer.

I'm very happy to discuss this though as this might be a similar direction to how EnergyWeb/EliaGroup are using VC-API exchanges currently:

1. Report to an external system on progress, such as the issuance of a VC.

For exchanges, callbacks can be configured to send the results of a presentation submission.
To configure the callbacks, we use the notion of an Exchange Definition.

2. Retrieve data from an external system to use in an exchange.

Rather than retrieve data from an external system, we allow the Issuer App to push the VC into the Presentation Service to be returned to the Wallet Service.

The key requirement that we're trying to support is asynchronous processing by the Issuer App. For example, perhaps there is could be manual review of credentials provided by the Wallet Service.
To signal this asynchrony to the WalletService, we use the MediatedExchange interaction type from VPR. w3c-ccg/vp-request-spec#17

The challenge I see with the sequence proposed in the initial post is that I think step 8 is the HTTP response to the request in step 3. If so, this means that step 4 needs to be relatively quick. However, maybe this is an implementation detail or there's an easy way around it.

The asynchronous sequence that EnergyWeb/EliaGroup are using looks like this:

sequenceDiagram
autonumber

participant ws as Wallet Service
participant ia as Issue App (Busines Logic)
participant ps as Presentation Service
participant is as Issue Service

ws->>ps: Request VC (VC-PI)
activate ps
  ps->>ws: Request authentication (VC-API + VPR)
deactivate ps

ws->>ps: Provide authentication (VC-API + VP)

ps->>ia: Notify of submission

ia->>is: Issue VC (VC-API)
activate is
  is->>ia: Issued VC (VC-API)
deactivate is

ia->>ps: Provide issued VC

ws->>ps: Request Issued VC (VC-API, Possibly providing auth again)
activate ps
  ps->>ws: Return VC
deactivate ps

Loading

[msporny]

This was discussed on the 2022-07-12 call. [[LINK HERE]]

[msporny]

With respect to the concept of a "Presentation Service" vs. an "Exchanger Service" ... @dlongley suggested that we have two classes of services. @jandrieu mentioned "Presentation Service" is "Holder Service" (credential derive, create, and get). @David-Chadwick noted that OIDC flows integrate tokens for issuing and refresh into Holder service.

What we might need is the concept of a "Holder Service" and a "Exchanger Service" (which might be absorbed by the Issuer App in some cases).

PR needed: Organize the presentation APIs under the "Holder Service" (for now) and introduce the concept of an "Exchanger Service" that may or may not be absorbed by the Issuer App.

[dlongley]

A PR should definitely specify how to return a redirectUrl at the end of an exchange for a client to use / get back into the channel where an exchange started. Doing web-hooks, etc. is much more open-ended and we need polling to work whether or not push notification style optimizations can be used.

[msporny]

The group discussed this on the 2024-01-23 call:

@dlongley noted that there are two different ways callbacks can be supported:

• Optionally, return a redirect URL at the end of an exchange that could be included in the final response at the end of an exchange which would be optionally followed by client doing the exchange. That could be helpful for binding something back to a channel where it originated.
• Other types of callbacks could be sending back-end messages (not re-directs), but "push notifications" (aka web hooks) during an exchange. These types of systems need to be resilient (failure to deliver) and so you'd need some kind of polling mechanism to get state of an exchange. Specifying that now might be more about optimization in an optimistic case (but still need polling).

It's not clear what text to write for the "web hook" piece. It's clear what would need to be written for "redirect URL" and "poll" (where web hooks would be an optimization on top).

@mbuchil said that many of these things are defined outside of the API, might be a slippery slope to dictate how this works. @jandrieu noted he likes web hooks, but we do need to figure out polling (to deal w/ failure). Could use notion for "interact" to frame how web hook could be done. @PatStLouis noted that there could be a "/web-hooks/" endpoint. @jandrieu noted that other constraint we could provide -- web hooks could be provided by coordinators (so we could focus our efforts there wrt. what to define.

It was decided that the group would try the most straightforward approach first, which is to provide a redirect URL first and then a few paragraphs around considerations wrt. web hooks vs. polling.

[msporny]

The group discussed this on 2024-05-28 call.

@dlongley recommended closing #295 and keeping issue #347 since it's more specific. The most useful place to put callbacks right now is in exchanges. @jandrieu +1 to solve the more specific use case (this issue). @PatStLouis reading #295, use case identified, report to external system on progress in an exchange, somewhat of a different use case. Make sure threads in other issue are captured here. @dlongley didn't think that there is a use case to report back on progress of issuance (atomic operation of issuance API). Use cases are around exchanges, other issue has been opened for a long time, it's still open/linked if it's not exchange related, let's close to make progress. @jandrieu noted that point of exchanges is to be abstraction, right layer to handle callbacks in general, this isn't just simpler use case, among APIs that are synchronous, we can move async stuff to exchanges (where all callback stuff moves).

The group decided to focus the callback URL discussion wrt. exchanges in issue #347 and close issue #295 because it was believed that by addressing callbacks in exchanges that it would address most, if not all, callback use cases.