Versions Compared

Version Old Version 42 New Version Current
Changes made by

Viktor Radchenko

Viktor Radchenko

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Info

Note: the fields values in WebhookCredentialValuesDTO[ ] should all be string.

According to the attribute type, which is set in the credential schema, values should be set to:
Text — text itself
Date — string with the number of seconds since epoch.
Number — number as string. If this number is float, than '.' used as decimal point "222.2222"
ImageURL -- url as string. // NOT USED YET
Enumeration -- numeric enumeration value as string, i.e. "0", "1",..etc

Actual value types will be casted on credential issue according to the credential schema attribute types.

Webhook in case of success invocation should return json with the following fields:

Code Block
languagejson
{
  serviceDid: string; //  public service DID, should be the same as in request
  subscriberConnectDid: string; // connect DID, should be the same as in request
  actionEventId: string;  //  event
  issuedCredentials:  WebhookCredentialValuesDTO[ ];  // array of issued credentials 
                                                      // in case you want to issue them 
                                                      // immediately. See the structure above.
  // revokedCredentials: [] // can be kept as an empty array, not used
}
Info

Note: if third-party systems want to deny or system wants postpone the issuing of a credential back to a user, then it should return credentials with empty fields.

Credential external verification Webhook

Can be configured to perform validation of credentials behind ProofSpace (such as checking that the hash is present in the blockchain or checking the root authority of the certificate).

...

If third-party system wants to fail the event on credentials receive, then it should return the following response:

Code Block
languagejson
{
    ok: false;
    serviceDidmessage: string;       // Message  public DID of service, which call actionto be shown in the app to the user
    subscriberDidactionEventId: string;  //  connectevent
DID of subscriber   credentialIdtype: string; 'failure';
    integrationOutput?: { //  credentialId, registered in blockchainOptional. Interaction extension info, which contains:
      integrationId,    schemaId: string;  // schemaExtension ID.
id   fields: { name: string, value: string } [];logData,             // array of fields.
}

and return the structure with the following fields:

Code Block
  Log information to be shown on the dashboard for the event.
    } 
}

Credential Issue Webhook

Credential issued webhook is called by the third-party to ProofSpace server via URL:

<container-root>/service/:serviceDid/webhook-accept/credendials-issued

i.e. for the ProofSpace cloud service, this should be:

https://platform.proofspace.id/service-backend/v1/service/:serviceDid/webhook-accept/credentials-issued

where: serviceDid is a public DID of the credential issuer.

For the interaction triggered by the ProofSpace App, where the subscriberEventId already exists and is known by the third party the JSON structure should be as follows:

Code Block
breakoutModewide
languagejson
{
  okserviceDid: booleanstring;   // true if check was successful, false otherwise  Public DID of the service which issues the credential, the same as in the query path.
  errorMessage?subscriberConnectDid: string;  //  optional// errorUser messageconnection ifDID checkwith wasthe unsuccessfulservice
  extracredentials: {WebhookCredentialValuesDTO[];  //  Array of the credentials to be issued in the interaction  optional extra information which contains
      schemaId?: string;   //  optional schemaId of returned fields.(the same structure as in Interaction Webhook above).
  subscriberEventId: string; // actionEventId which has been previously received in Interaction Webhook
  actionParams?: Array<NameValueDTO>;  // Optional. Set of parameters which identify the interaction instance. 
                                       // If present - info should contain fields from this schema, 
                           // otherwise info contains fields in any form.
      info: { name: string, value: string }[]; //values
      format: string;  // optional format description for values, encoded in info. Used when we have more than one instance of interaction specified by actionTemplate and need to select one.
}

For the incoming push from service interaction triggered from the third party side via API the JSON structure should be as follows:

Code Block
breakoutModewide
languagejson
{
  serviceDid: string;            //  Public DID of the service which issues the credential, the same as in the query path.
  subscriberConnectDid: string;  // User connection DID with the service.
  credentials: WebhookCredentialValuesDTO[];  //  Array of the credentials to be issued in the interaction (the same structure as in Interaction Webhook above).
  actionTemplate?: string;       // Action ID from the dashboard to identify the interaction.
  actionParams?: Array<NameValueDTO>;  // Optional. Set of parameters which identify the interaction instance. 
                                       // should be ‘plain’ or ‘json’.
  }
}

Credential Issue Webhook

...

 Used when we have more than one instance of interaction specified by actionTemplate and need to select one.

And the returned structure is:

Code Block
languagejson
{
  ok: boolean   //  if credential issuing was successful
  error?: {  // optional block which contains message
    message: string;
  }
}

Credential Issuing Failure Webhook

Credential issued failure webhook is called by the third-party to ProofSpace server via URL:

<container-root>/service/:serviceDid/webhook-accept/credendials-issuing-issuedfailed

i.e. for the ProofSpace cloud service, this should be:

https://platform.proofspace.id/service-backend/v1/service/:serviceDid/webhook-accept/credentials-issued/.credendials-issuing-failed

where: serviceDid is a public DID of the credential ownerissuer.

ProofSpace accepts the structure with the following fieldsFor the interaction triggered by the ProofSpace App, where the subscriberEventId already exists and is known by the third party, the JSON structure should be as follows:

Code Block
breakoutModewide
languagejson
{  
  messageType: 'credentialIssueFailed';
  serviceDid: string;  //  publicPublic DID of the service which issues the credential, the same as in the query path.
  subscriberConnectDid: string;  // User connect DID of  subscriber for this serviceconnection DID, whose attempt to receive credentials was rejected.
  errorMessage: string; // Error message to be logged in the dashboard event log (can be technical).
  subscriberErorrMessage?: string; // // Optional. Error message to be shown to the user as a popup in the ProofSpace App.
  credentials?: WebhookCredentialValuesDTO[];  // Optional. arrayArray of credentials that issued. failed to be issued (the same as in Interaction Webhook above).
  subscriberEventId: string; // issuedAt:  UTC timestamp of issued date in milliseconds
  subscriberEventId: string; // optional event-id which can be previously received in Interaction Webhook (actionEventId), Event ID which has been previously received in Interaction Webhook (actionEventId), if we want to fail issuing credential in this event.
  actionParams?: Array<NameValueDTO>;  // Optional. Set of parameters which identify the interaction instance. 
                                       // Used ifwhen we want  issue credential in this event. If absent, engine will find interaction which 
   have more than one instance of interaction specified by actionTemplate and need to select one.
  integrationOutput:{    // Optional. Interaction extension info, which contains:
    integrationId,       // Extension ID.
    logData,             // issueLog information thisto credentialbe andshown ifon the dashboard for choicethe isevent.
unequivocal - will} create a new event.  
  actionTemplate?
}

For the incoming push from service interaction triggered from the third party side via API, when the user should receive a failed notification in the ProofSpace App, the JSON structure should be as follows:

Code Block
breakoutModewide
languagejson
{  
  messageType: 'credentialIssueFailed';
  serviceDid: string;  //  Public DID of the service which issues the credential, the same as in the query path.
  subscriberConnectDid: string;  // User connection DID, whose attempt to receive credentials was rejected.
  errorMessage: string; // optional actionTemplate for interaction with mode ‘Push from Server’ Error message to be logged in the dashboard event log (can be technical).
  subscriberErorrMessage?: string; // // Optional. Error message to be shown to the user as a popup in the ProofSpace App.
    credentials?: WebhookCredentialValuesDTO[];  // Note, that If actionTemplate is present, then subscriberEventId should be absent and vice-versa. Optional. Array of credentials that failed to be issued (the same as in Interaction Webhook above).
  actionTemplate: string,  // Action ID from the dashboard to identify the interaction.
  actionParams?: Array<NameValueDTO>;  // Optional. Set of parameters which identify the interaction instance. 
                                        // Used, when we have more than one instance of interaction specified by actionTemplate and need to select one.
 }

And the returned structure is:

Code Block
languagejson
{
  ok: boolean integrationOutput:{    // Optional. Interaction extension info, which contains:
    integrationId,       //  if credential setting was successfulExtension ID.
    logData,          error?: {  // optionalLog blockinformation whichto containsbe messageshown on the dashboard for message: string;the event.
  } 
}

Retrieving Service Public Key

...

Webhook

This functionality by the third-party to ProofSpace server via URL:

...