ProofSpace provides the following integration points:
Called by ProofSpace:
Called by third-party:
Webhook calls are performed as HTTPS Post requests, where input and output are json encoded values.
Authentication Schemas
We support two authentication schema:
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.Bearer Token
Each call should have an Authorisation header with the valueBearer {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 WebHook integration examples contains Javascript examples.
...
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.
...
Webhook specifications
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.
Interaction Webhook dashboard setup documentation
The input contains the following fields:
Code Block | ||
---|---|---|
| ||
{ publicServiceDid: string; |
...
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
...
// your service DID
subscriberConnectDid: string; // connect DID of the user
actionId: string; // interaction id from dashboard
actionInstanceId: string; // interaction instance id
actionEventId: string; // id of the event (unique for the service)
actionParams: {name: string, value: string}[]; // array of parameters, configured in action
receivedCredentials: WebhookCredentialValuesDTO[ ] ; // array of required credentials
} |
Where WebhookCredentialValuesDTO consists of:
Code Block | ||
---|---|---|
| ||
{ 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 |
...
, not used) // utcRevokedAt?: number; // time when credential was revoked (optional, not used). } |
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: 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 | ||
---|---|---|
| ||
{ 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 postpone the issuing of a credential back to a user, then it should return credentials with empty fields |
...
. |
Credential external verification Webhook
...
It should accept json with the following fields:
Code Block | ||
---|---|---|
| ||
{ 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:
Code Block | ||
---|---|---|
| ||
{ 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 installationProofSpace cloud service, this should be:
where: serviceDid is a public DID of the credential ownerissuer.
ProofSpace accepts the structure with the following fields:
Code Block | ||||
---|---|---|---|---|
| ||||
{ 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 Interaction Webhook above).
// issuedAt: UTC timestamp of issued date in milliseconds
subscriberEventId: string; // optional event-id which can be previously received in Interaction Webhook (actionEventId),
// if we want issue credential in this event. If absent, engine will find interaction which
// issue this credential and if the choice is unequivocal - will create a new event.
actionTemplate?: string; // optional actionTemplate for interaction with mode ‘Push from Server’.
// Note, that If actionTemplate is present, then subscriberEventId should be absent and vice-versa.
actionParams?: Array<NameValueDTO>; // Set of parameters which identify 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 | ||
---|---|---|
| ||
{ ok: boolean // if credential setting was successful |
...
error?: { // optional block which contains message |
...
message: string; |
...
Retrieving Service Public Key webhook
...
}
} |
Credential Issuing Failure Webhook
Credential issued failure webhook is called by the third-party to ProofSpace server via URL:
<container-root>/service/:serviceDid/publicwebhook-infoaccept/public-key/name
<!-- Footnotes themselves at the bottom. -->
Notes
[^1]:
...
credendials-issuing-failed
i.e. for the ProofSpace cloud service, this should be:
where: serviceDid is a public DID of the credential issuer.
ProofSpace accepts JSON structure with the following fields:
Code Block | ||||
---|---|---|---|---|
| ||||
{
messageType: 'credentialIssueFailed'; // optional constant.
serviceDid: string; // public DID of service which issues credential, the same as in the query path.
subscriberConnectDid: string; // user connection DID, whose attempt to issue credentials was rejected.
errorMessage: string; // error message which should be logged (can be technical)
credentials?: WebhookCredentialValuesDTO[]; // Optional, array of credentials that failed to be issued. (the same as in Interaction Webhook above).
subscriberEventId: string; // optional event-id which can be previously received in Interaction Webhook (actionEventId),
// if we want to fail issueing credential in this event.
actionParams?: Array<NameValueDTO>; // Set of parameters which identify interaction instance.
// Used, when we have more than one instance of interaction specified by actionTemplate and need to select one.
integrationOutput:{ // optional integration info, which contains:
integrationId,
prevIntegrations, // other integrations, which was processed in this event
logData, // log information to be shown on the dashbord for the event
}
} |
Retrieving Service Public Key webhook
This functionality by the third-party to ProofSpace server via URL:
<container-root>/service/:serviceDid/public-info/public-key/<key name from dashboard>
For the ProofSpace cloud service <container-root> is https://platform.proofspace.id
Notes
Info |
---|
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(no personal or user data is monitored) in the Dashboard for that service. |