Integration Webhooks API Overview

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

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:

{
  publicServiceDid: string;  // 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:

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

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:

{
  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
}

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

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

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:

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

And the returned structure is:

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-failed

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

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

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:

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:

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

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.