# VC-API Holder Notification

## Response to https://github.com/w3c-ccg/vc-api/issues/295

The initial post in this issue mentions two use cases:
> 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.

These uses cases then prompted callbacks to the "Issuer App".

Another use case I have in mind is "Asynchronously provide credentials to Holder Coordinator". This would be used in the event that the issuer needs time to issue the credential and cannot respond synchronously to the holder.

The use case sequence could look as shown below.
This is an adaptation of the sequence in the initial post in this issue.
Note that the participant names are adjusted to related the new naming used in [VC-API architecture](https://w3c-ccg.github.io/vc-api/#architecture-overview)

sequenceDiagram
    participant WS as Holder Coordinator<br>(Wallet Service)
    participant PS as Issuer Coordinator<br>(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->>WS: Return async comms info (VC-API + VPR?)
    WS->>PS: Provide async comms config (e.g. webhook)
    Note over WS, PS: Some time passes...
    PS->>IS: Issue VC (VC-API)
    IS->>PS: Issued VC (VC-API)
    PS->>WS: Issued VC to webhook (VC-API + VP)

If the above sequence is reasonable, the "Return async comms info" and "Provide async comms config" would need to be defined.

One idea for "Request webhook" is that a VPR could be used to request the webhook.
I think use of the VPR for this may be subverting the intent of the VPR a bit as the `interact` property is to be used, however it is a viable solution.

Perhaps it could function by defining a new [VPR interaction type](https://w3c-ccg.github.io/vp-request-spec/#interaction-types) could be defined.
A VPR with this new interaction type could like as follow:

...
"interact": {
  "service": [{
    "type": "CredentialDeliveryWebhook",
    "serviceEndpoint": "https://example.com/what-is-your-webhook-endpoint"
  }]
}
...

In step 5 above, the Holder Coordinator would reply to "https://example.com/what-is-your-webhook-endpoint" with an HTTP endpoint to which the Issuer Coordinator could POST to once the credential is issued.

Perhaps a better than using a VPR would be for the Issuer Coordinator to respond directly with communication configuation information (in step 4).
For this, I have in mind, something similar to the Shared Signals Framework [Transmitter Configuration object](https://github.com/duo-labs/sharedsignals/blob/main/transmitter_spec/schemas/TransmitterConfiguration.yaml).
The Holder Coordinator could then use the endpoints in the configuration object to communicate how they would like to receive the credential (e.g. push vs pull).
See this guide for how it is done for Shared Signals: https://sharedsignals.guide/#updateconfiguration

An improvement to the above may be to communicate to the holder earlier that a asynchronous communication is required for the exchange.

sequenceDiagram
    participant WS as Holder Coordinator<br>(Wallet Service)
    participant PS as Issuer Coordinator<br>(Presentation Service)
    participant IS as Issuer Service
    autonumber
    WS->>PS: Request VC (VC-API)
    PS->>WS: Return async comms info (VC-API + VPR?)
    PS->>WS: Request authentication (VC-API + VPR)
    WS->>PS: Provide authentication (VC-API + VP)
    PS->>WS: Return async comms info (VC-API + VPR?)
    WS->>PS: Provide async comms config (e.g. webhook)
    Note over WS, PS: Some time passes...
    PS->>IS: Issue VC (VC-API)
    IS->>PS: Issued VC (VC-API)
    PS->>WS: Issued VC to webhook (VC-API + VP)