ProofSpace provides the following integration points:

Called by ProofSpace:

1. Interaction Webhook

2. Credential External Verification Webhook

Called by third-party:

1. Credential Issuing Webhook

Webhook calls are performed as HTTPS Post requests, where input and output are json encoded values.

Authentication Schemas

We support two authentication schema:

1. Request Signature
   Each call should have an additional X-Body-Signature header with the value of the third-party’s sha3-256 signature in base64 encoding. ProofSpace and third-parties should exchange public keys before integration.

2. Bearer Token
   Each call should have an Authorisation header with the value Bearer {token}, where the token is a base64 representation of the JsonWebToken as defined in RFC 7519.

• In the request from ProofSpace, 'iss' field is a public DID of the service[^1].

• In request to ProofSpace, 'aud' field should be a public DID of the service.

• ProofSpace and third-parties should exchange public keys of sha secrets before integration.

Repository WebHooks integration examples contains Javascript examples.

Demo: Corresponding ProofSpace demo interactions with integration webhooks can be found in the ProofSpace App. Android or iOS

You may navigate to ProofSpace Demo service by searching it in the App or by scanning the service QR with the Scan button in the bottom navigation bar.

Description of calls

Interaction Webhook

An interaction webhook can be called while the user performs an interaction.

It receives information about current activity and received credentials (details below) and may return information about issued credentials.

The input contains the following fields:

• publicServiceDid: string; -- public DID of service which owns the action.

• subscriberConnectDid: string; -- connect DID of the subscriber to this service.

• actionId: string; // action template

• actionInstanceId: string; // action instance.

• actionEventId: string; // id of the event (unique for service)

• actionParams: {name: string, value: string}[]; // array of parameters, configured in action

• receivedCredentials: WebhookCredentialValuesDTO[ ] ; //array of required credentials.

Where WebhookCredentialValuesDTO consists of:

• credentialId: string; // credentialId

• schemaId: string; // schemaId

• fields: { name: string, value: string }[]; // credentials from phone

• utcIssuedAt: number; // utc time in milliseconds

• revoked: boolean; // is this credential revoked. (optional)

• utcRevokedAt?: number; // time when credential was revoked (optional).

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

• 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.

• revokedCredentials: [] // can be kept as an empty array

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

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).

It should accept json with the following fields:

• serviceDid: string; // public DID of service, which call action

• subscriberDid: string; // connect DID of subscriber

• credentialId: string; // credentialId, registered in blockchain

• schemaId: string; // schema id

• fields: { name: string, value: string } []; // array of fields.

and return the structure with the following fields:

• ok: boolean; // true if check was successful, false otherwise.

• errorMessage?: string // optional error message if check was unsuccessful

• extra: // optional extra information which contains

  • schemaId?: string; // optional schemaId of returned fields. 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. should be ‘plain’ or ‘json’.

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 SaaS installation, this should be:

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

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

ProofSpace accepts the structure with the following fields:

• serviceDid: string; // public DID of service which issues credential, the same as in the query path.

• subscriberConnectDid: string; // connect DID of subscriber for this service

• credentials: WebhookCredentialValuesDTO[]; // array of credentials issued. (the same as in ‘action’ webhook).

• issuedAt: UTC timestamp of issued date in milliseconds.

And the returned structure is:

• ok: boolean // if credential setting was successful

• error?: // optional block which contains message

  • message: string;

Retrieving Service Public Key webhook

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

<container-root>/service/:serviceDid/public-info/public-key/name

<!-- Footnotes themselves at the bottom. -->

Notes

[^1]:

 A “service” is an instance of the ProofSpace Dashboard. 
 ProofSpace charges a subscription fee per service and all interactions 
 for a service will be created and monitored in the Dashboard for that service.