SSI Verification Integration

Introduction

Objective

This document explains how to integrate Gataca’s SSI Credential Verification Service into your infrastructure. The integration enables your system to verify Verifiable Credentials (VCs) in compliance with W3C DID and Verifiable Credentials standards.

Target Audience

Developers, solution architects, and system administrators responsible for integration.

Key Benefits

• Verify interoperable Verifiable Credentials seamlessly.

• Ensure compliance with international SSI standards for trusted verification.

• Enhance trust by confirming data authenticity and integrity.

• Enable decentralized and privacy-preserving credential verification.

• Streamline user experiences with fast and secure verification processes.

Prerequisites

• Internet access to consume the exposed APIs over HTTPS.

• Ports: 443 (TLS/SSL).

Integration Workflow

The following steps outline the workflow for credential verification:

1. The client sends a credential verification request to the API.

2. The API validates the request and processes the data.

3. The backend verifier verifies the data exchanged.

Sequence Diagram

The diagram below illustrates the SSI authentication flow. This documentation will only focus on the steps relevant to the integration process.

• User Wallet: Gataca Wallet

• Relying Party App (also known as a service provider): refers to the web or mobile application that requires authentication from a user - this is your organization.

• Connect: Verifier component in Gataca Studio

Sequence Diagram

API Endpoints

Detailed API endpoint documentation (including request/response formats, parameters, and error codes) is provided in the Swagger documentation.

Swagger UI

Step-by-Step Integration Guide

Initial Configuration

1. Generate API Key

Log in to the Gataca Studio portal and generate an API key, ensuring it is linked to a specific Verification Template if required. Once the API key is successfully generated, click the Save button to confirm the configuration.

Gataca Studio - Generating API Key

2. Obtain API Key Credentials

After generating the API key, the associated credentials will be displayed. Store this information securely, as it will be required for authenticating requests to the platform. Note that the credentials may not be retrievable again.

Gataca Studio - API Key Credentials

Authentication

The majority of Gataca endpoints are protected to avoid unauthorized access and security issues. This protection is based on access tokens issued using basic authentication.

3. Obtain an Access Token

Use the platform’s login endpoint to retrieve an Access Token. This token is required to authenticate and authorize all protected operations within the system. Make sure to securely store the token for subsequent API requests.

Request Example

http

POST /admin/v1/api_keys/login
Host: nucleus.gataca.io
Authorization: Basic [API-KEY-CREDENTIALS]
tenant: [TENANT]
ssiconfig: [TEMPLATE-ID]
Content-Type: application/json

API-KEY-CREDENTIALS: base64(api-key id:api-key secret) - You must provide the API Key ID (UUID) and secret given when creating the API Key in Studio, encoded in base64 format in the HTTP request header.

TENANT: A tenant is a logical instance that isolates data and configurations, identified by a unique tenant ID to ensure separation from other clients.

TEMPLATE-ID: Identifier of the template used for this verification. These identifiers are configured in Studio.

Response Example

http

HTTP/1.1 200 OK
Content-Type: application/json
Token: ACCESS-TOKEN
Token_type: jwt

{
    "message": "SUCCESS"
}

Details: Swagger

Verifying Credentials

To verify a Verifiable Credential and ensure its association with a subject, the credential’s authenticity and integrity must first be confirmed. This requires a verification process, where the credential is validated against its associated DID (Decentralized Identifier) and checked for compliance with cryptographic proofs.

Once the credential and its associated data are successfully validated, the verifier can trust the information it contains and proceed to grant access or perform the required action based on the verified details.

4. Generating Verification Process instance

Request Example

http

POST /api/v3/sessions
Host: connect.gataca.io
Authorization: jwt [ACCESS-TOKEN]
Content-Type: application/json

{
    "ssiConfigId":"VERIFICATION-TEMPLATE-ID"
}

• ACCESS-TOKEN: Access token received from the authentication request (This authentication must be executed by an application linked to the tenant selected into the authentication request).

• VERIFICATION-TEMPLATE-ID: This is the Verification Template Identifier you gave in the configuration settings when creating your verification template in Gataca Studio.

Response Example

http

HTTP/1.1 201 OK
Content-Type: application/json

{
   "authentication_request":"openid-vp://?client_id=https%3A%2F%2Fconnect.gataca.io%2Fapi%2Fv3%2Ftenants%2F29KKv46fz3kZ5jvxjBqtAq9RvqJwoA2X%2Foidc-verifier%2FTest\u0026redirect_uri=https%3A%2F%2Fconnect.gataca.io%2Fapi%2Fv3%2Ftenants%2F29KKv46fz3kZ5jvxjBqtAq9RvqJwoA2X%2Foidc-verifier%2FTest%2Fauthorization-responses%2F4m8TLXcRUDpMrXkzorhoTpwMu6pkw4pUtHVSBf422c98\u0026request_uri=https%3A%2F%2Fconnect.gataca.io%2Fapi%2Fv3%2Ftenants%2F29KKv46fz3kZ5jvxjBqtAq9RvqJwoA2X%2Foidc-verifier%2FTest%2Frequest%2F4m8TLXcRUDpMrXkzorhoTpwMu6pkw4pUtHVSBf422c98\u0026response_mode=direct_post\u0026response_type=vp_token\u0026scope=openid",
   "presentation_definition":{
      "dataAgreement":{
         "@context":"https://schema.igrant.io/data-agreements/v1",
         "data_receiver":{
            "id":"did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv",
            "consent_duration":365,
            "form_of_consent":"explicit",
            "url":"https://connect.gataca.io"
         },
         "event":[
            {
               "principle_did":"did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv",
               "proof":[
                  {
                     "created":"2025-01-27T18:33:35Z",
                     "creator":"did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv#keys-1",
                     "domain":"gataca.io",
                     "nonce":"OMHLoaLQ5YpcyrXg0tqAxWCD9vSlkED8MeaWyDN0Urw=",
                     "proofPurpose":"assertionMethod",
                     "signatureValue":"lo75h936wQw3Jok41N1C6jzrEt5Sb20KBQ8xdefG1UOuKHmX11cTJAHZzNSyXJHEy95pCIcTY2UMDcUuhGuyDQ",
                     "type":"JcsEd25519Signature2020",
                     "verificationMethod":"did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv#keys-1"
                  }
               ],
               "state":"Preparation",
               "version":"0",
               "timestamp":1738002815098
            }
         ],
         "id":"2obqpkUVGy367qdpnrdpkAdSzVodZz4bhcE32Bs5movF",
         "personal_data":[
            {
               "attribute_name":"emailCredential",
               "attribute_sensitive":true,
               "purposes":[
                  ""
               ]
            }
         ],
         "purposes":null,
         "template_id":"Test",
         "template_version":"1",
         "version":"0"
      },
      "name":"Test",
      "id":"4m8TLXcRUDpMrXkzorhoTpwMu6pkw4pUtHVSBf422c98",
      "format":{
         "jwt":{
            "alg":[
               "EdDSA",
               "ES256",
               "ES256K"
            ]
         },
         "jwt_vp":{
            "alg":[
               "EdDSA",
               "ES256",
               "ES256K"
            ]
         },
         "ldp":{
            "proof_type":[
               "JsonWebSignature2020",
               "Ed25519Signature2018",
               "EcdsaSecp256k1Signature2019",
               "RsaSignature2018"
            ]
         },
         "ldp_vp":{
            "proof_type":[
               "JsonWebSignature2020",
               "Ed25519Signature2018",
               "EcdsaSecp256k1Signature2019",
               "RsaSignature2018"
            ]
         }
      },
      "submission_requirements":[
         {
            "name":"Mandatory data",
            "purpose":"Basic data to provide the service",
            "rule":"all",
            "from":"mandatory"
         },
         {
            "name":"Optional data",
            "purpose":"Additional data to enrich the service",
            "rule":"pick",
            "min":0,
            "from":"optional"
         }
      ],
      "input_descriptors":[
         {
            "id":"emailCredential",
            "name":"emailCredential",
            "group":[
               "mandatory"
            ],
            "constraints":{
               "fields":[
                  {
                     "path":[
                        "$.type[-1:]",
                        "$.vc.type[-1:]"
                     ],
                     "purpose":"The claim must be of a specific type",
                     "filter":{
                        "type":"string",
                        "pattern":"emailCredential"
                     },
                     "intent_to_retain":true
                  },
                  {
                     "path":[
                        "$.issuer",
                        "$.vc.issuer",
                        "$.iss"
                     ],
                     "purpose":"Assert the trust of the issuer",
                     "filter":{
                        "type":"string",
                        "pattern":"(||||did:gatc:24gsRbsURij3edoveHv81jt9EnhggrnR|did:ebsi:zx23VjG43EsmTuTA3EvQQnd|did:ebsifnmt:zx262gXXXuRXxDfDdkf8oLG|did:gatc:24uATHrisWkLFnDMgRHcwQvzkjLB8tWE)"
                     }
                  }
               ],
               "statuses":{
                  "active":{
                     "directive":"required"
                  }
               }
            }
         }
      ],
      "proof":[
         {
            "created":"2025-01-27T18:33:35Z",
            "creator":"did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv#keys-1",
            "domain":"gataca.io",
            "nonce":"GMAa84Mp_PdcyTN6ebNryHpRcNw970yrsoEBKlSPxY8=",
            "proofPurpose":"authentication",
            "signatureValue":"atQqJ4AMcpE0VBdHv7VAVdVwRMim2GTrGudt1rsERxIC5L57WCzDREHdL6mjQ8gEmYlZur9pKC48amxgPnaRDg",
            "type":"JcsEd25519Signature2020",
            "verificationMethod":"did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv#keys-1"
         }
      ]
   }
}

This response is too big to be displayed in a QR code, so only the authentication_request field is shown to represent the session in the QR code. This session identifier (id) is required for the following step, so make sure to copy it.

In the section requested are all the Verifiable Credentials requested by the Verifier, which all follow the same structure. In this example, it is requesting this VC type.

• Email Name: emailCredential

The structure of the Verifiable Credential shows the credential type (email), that the credential must be shared (it is mandatory), needs to be issued by a trusted issuer as the Trust Level is 1 (Validation), and the purpose for requesting the credential (authentication).

The session generation step can be automatic using GatacaQR, a JavaScript component allowing any relying party to generate a session in a simple way.

You will find the GatacaQR component code repositories at the end of this documentation.

5. Validating the Issuance Process

Getting the information from a specific verification process is also possible using the command below. Instead of retrieving information from a set of verification processes, this command retrieves the information from a specific verification process (using the process identifier).

Request Example

http

GET /api/v3/sessions/[VERIFICATION-ID]
Host: connect.gataca.io
Authorization: jwt [ACCESS-TOKEN]
Content-Type: application/json

• VERIFICATION-ID : Session identifier. It must be recovered from the generated session response (Step 3). In this case, 4m8TLXcRUDpMrXkzorhoTpwMu6pkw4pUtHVSBf422c98 .

• ACCESS-TOKEN: Access token received from the authentication request (This authentication must be executed by an application linked to the tenant selected into the authentication request).

Response Example

HTTP/1.1 202 Accepted
Content-Type: application/json

{
    "Id": "AUFu7juZg2UgnUzaELCsWbhGQduMRzxzQaoww1aLzySN",
    "PresentationSubmission": null,
    "PresentationSubmissionFormat": "",
    "Validations": null,
    "PresentationDefinition": {
        "dataAgreement": {
            "@context": "https://schema.igrant.io/data-agreements/v1",
            "data_receiver": {
                "id": "did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv",
                "consent_duration": 365,
                "form_of_consent": "explicit",
                "url": "https://connect.gataca.io"
            },
            "event": [
                {
                    "principle_did": "did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv",
                    "proof": [
                        {
                            "created": "2025-01-27T19:16:20Z",
                            "creator": "did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv#keys-1",
                            "domain": "gataca.io",
                            "nonce": "ZN4VE13taIj_D6IBswsZwQ3wgjLCJJA-bdGBuTRxl8U=",
                            "proofPurpose": "assertionMethod",
                            "signatureValue": "6daZkZ8R1udFWELu8XYr1uOXvHy3SYT19fkspmPFzL_thfTiwl8w9QedmtSHgIMYpe75HPkUUBQp6B992Z6oBg",
                            "type": "JcsEd25519Signature2020",
                            "verificationMethod": "did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv#keys-1"
                        }
                    ],
                    "state": "Preparation",
                    "version": "0",
                    "timestamp": 1738005380501
                }
            ],
            "id": "76DdAevHf8TrphxTvDfny78fDZjTRj1qX4xXW4LMLJcV",
            "personal_data": [
                {
                    "attribute_name": "emailCredential",
                    "attribute_sensitive": true,
                    "purposes": [
                        ""
                    ]
                }
            ],
            "purposes": null,
            "template_id": "Test",
            "template_version": "1",
            "version": "0"
        },
        "name": "Test",
        "id": "AUFu7juZg2UgnUzaELCsWbhGQduMRzxzQaoww1aLzySN",
        "format": {
            "jwt": {
                "alg": [
                    "EdDSA",
                    "ES256",
                    "ES256K"
                ]
            },
            "jwt_vp": {
                "alg": [
                    "EdDSA",
                    "ES256",
                    "ES256K"
                ]
            },
            "ldp": {
                "proof_type": [
                    "JsonWebSignature2020",
                    "Ed25519Signature2018",
                    "EcdsaSecp256k1Signature2019",
                    "RsaSignature2018"
                ]
            },
            "ldp_vp": {
                "proof_type": [
                    "JsonWebSignature2020",
                    "Ed25519Signature2018",
                    "EcdsaSecp256k1Signature2019",
                    "RsaSignature2018"
                ]
            }
        },
        "submission_requirements": [
            {
                "name": "Mandatory data",
                "purpose": "Basic data to provide the service",
                "rule": "all",
                "from": "mandatory"
            },
            {
                "name": "Optional data",
                "purpose": "Additional data to enrich the service",
                "rule": "pick",
                "min": 0,
                "from": "optional"
            }
        ],
        "input_descriptors": [
            {
                "id": "emailCredential",
                "name": "emailCredential",
                "group": [
                    "mandatory"
                ],
                "constraints": {
                    "fields": [
                        {
                            "path": [
                                "$.type[-1:]",
                                "$.vc.type[-1:]"
                            ],
                            "purpose": "The claim must be of a specific type",
                            "filter": {
                                "type": "string",
                                "pattern": "emailCredential"
                            },
                            "intent_to_retain": true
                        },
                        {
                            "path": [
                                "$.issuer",
                                "$.vc.issuer",
                                "$.iss"
                            ],
                            "purpose": "Assert the trust of the issuer",
                            "filter": {
                                "type": "string",
                                "pattern": "(||||did:gatc:24gsRbsURij3edoveHv81jt9EnhggrnR|did:ebsi:zx23VjG43EsmTuTA3EvQQnd|did:ebsifnmt:zx262gXXXuRXxDfDdkf8oLG|did:gatc:24uATHrisWkLFnDMgRHcwQvzkjLB8tWE)"
                            }
                        }
                    ],
                    "statuses": {
                        "active": {
                            "directive": "required"
                        }
                    }
                }
            }
        ],
        "proof": [
            {
                "created": "2025-01-27T19:16:20Z",
                "creator": "did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv#keys-1",
                "domain": "gataca.io",
                "nonce": "VuWnEXbC-KDZmVJECpayg4w7T6YKAB-pWGMujy_I3gY=",
                "proofPurpose": "authentication",
                "signatureValue": "X3K_QfJhMWykCcQJ1D6qbOGn0xlLdbv1GhyqYoTUJUW7bzS27vH8Unh2xMO4EflwEo_hr_fwpyXsNF7rvy5lBQ",
                "type": "JcsEd25519Signature2020",
                "verificationMethod": "did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv#keys-1"
            }
        ]
    },
    "AuthRequest": {
        "exp": 1738005680,
        "iss": "https://connect.gataca.io/api/v3/tenants/29KKv46fz3kZ5jvxjBqtAq9RvqJwoA2X/oidc-verifier/Test",
        "response_type": "vp_token",
        "client_id": "https://connect.gataca.io/api/v3/tenants/29KKv46fz3kZ5jvxjBqtAq9RvqJwoA2X/oidc-verifier/Test",
        "redirect_uri": "https://connect.gataca.io/api/v3/tenants/29KKv46fz3kZ5jvxjBqtAq9RvqJwoA2X/oidc-verifier/Test/authorization-responses/AUFu7juZg2UgnUzaELCsWbhGQduMRzxzQaoww1aLzySN",
        "state": "EMi5jHoYFqicZ7frDQbdkfFa1sBK5grcXKVYRVgSYzk8",
        "scope": "openid",
        "response_mode": "direct_post",
        "nonce": "5GpefxLWz3BzLmR69b4wskqeYgE5ZZ21jAvgLXNZNAe4",
        "presentation_definition": {
            "dataAgreement": {
                "@context": "https://schema.igrant.io/data-agreements/v1",
                "data_receiver": {
                    "id": "did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv",
                    "consent_duration": 365,
                    "form_of_consent": "explicit",
                    "url": "https://connect.gataca.io"
                },
                "event": [
                    {
                        "principle_did": "did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv",
                        "proof": [
                            {
                                "created": "2025-01-27T19:16:20Z",
                                "creator": "did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv#keys-1",
                                "domain": "gataca.io",
                                "nonce": "ZN4VE13taIj_D6IBswsZwQ3wgjLCJJA-bdGBuTRxl8U=",
                                "proofPurpose": "assertionMethod",
                                "signatureValue": "6daZkZ8R1udFWELu8XYr1uOXvHy3SYT19fkspmPFzL_thfTiwl8w9QedmtSHgIMYpe75HPkUUBQp6B992Z6oBg",
                                "type": "JcsEd25519Signature2020",
                                "verificationMethod": "did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv#keys-1"
                            }
                        ],
                        "state": "Preparation",
                        "version": "0",
                        "timestamp": 1738005380501
                    }
                ],
                "id": "76DdAevHf8TrphxTvDfny78fDZjTRj1qX4xXW4LMLJcV",
                "personal_data": [
                    {
                        "attribute_name": "emailCredential",
                        "attribute_sensitive": true,
                        "purposes": [
                            ""
                        ]
                    }
                ],
                "purposes": null,
                "template_id": "Test",
                "template_version": "1",
                "version": "0"
            },
            "name": "Test",
            "id": "AUFu7juZg2UgnUzaELCsWbhGQduMRzxzQaoww1aLzySN",
            "format": {
                "jwt": {
                    "alg": [
                        "EdDSA",
                        "ES256",
                        "ES256K"
                    ]
                },
                "jwt_vp": {
                    "alg": [
                        "EdDSA",
                        "ES256",
                        "ES256K"
                    ]
                },
                "ldp": {
                    "proof_type": [
                        "JsonWebSignature2020",
                        "Ed25519Signature2018",
                        "EcdsaSecp256k1Signature2019",
                        "RsaSignature2018"
                    ]
                },
                "ldp_vp": {
                    "proof_type": [
                        "JsonWebSignature2020",
                        "Ed25519Signature2018",
                        "EcdsaSecp256k1Signature2019",
                        "RsaSignature2018"
                    ]
                }
            },
            "submission_requirements": [
                {
                    "name": "Mandatory data",
                    "purpose": "Basic data to provide the service",
                    "rule": "all",
                    "from": "mandatory"
                },
                {
                    "name": "Optional data",
                    "purpose": "Additional data to enrich the service",
                    "rule": "pick",
                    "min": 0,
                    "from": "optional"
                }
            ],
            "input_descriptors": [
                {
                    "id": "emailCredential",
                    "name": "emailCredential",
                    "group": [
                        "mandatory"
                    ],
                    "constraints": {
                        "fields": [
                            {
                                "path": [
                                    "$.type[-1:]",
                                    "$.vc.type[-1:]"
                                ],
                                "purpose": "The claim must be of a specific type",
                                "filter": {
                                    "type": "string",
                                    "pattern": "emailCredential"
                                },
                                "intent_to_retain": true
                            },
                            {
                                "path": [
                                    "$.issuer",
                                    "$.vc.issuer",
                                    "$.iss"
                                ],
                                "purpose": "Assert the trust of the issuer",
                                "filter": {
                                    "type": "string",
                                    "pattern": "(||||did:gatc:24gsRbsURij3edoveHv81jt9EnhggrnR|did:ebsi:zx23VjG43EsmTuTA3EvQQnd|did:ebsifnmt:zx262gXXXuRXxDfDdkf8oLG|did:gatc:24uATHrisWkLFnDMgRHcwQvzkjLB8tWE)"
                                }
                            }
                        ],
                        "statuses": {
                            "active": {
                                "directive": "required"
                            }
                        }
                    }
                }
            ],
            "proof": [
                {
                    "created": "2025-01-27T19:16:20Z",
                    "creator": "did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv#keys-1",
                    "domain": "gataca.io",
                    "nonce": "VuWnEXbC-KDZmVJECpayg4w7T6YKAB-pWGMujy_I3gY=",
                    "proofPurpose": "authentication",
                    "signatureValue": "X3K_QfJhMWykCcQJ1D6qbOGn0xlLdbv1GhyqYoTUJUW7bzS27vH8Unh2xMO4EflwEo_hr_fwpyXsNF7rvy5lBQ",
                    "type": "JcsEd25519Signature2020",
                    "verificationMethod": "did:gatc:28ArBPMsHTtwQN8CvzVKgdr9dUEY83gv#keys-1"
                }
            ]
        }
    },
    "RequestedAt": null,
    "CreatedAt": "2025-01-27T19:16:20.504775Z",
    "UpdatedAt": "2025-01-27T19:16:20.516899Z",
    "ExpiredAt": "2025-01-27T19:21:20.504774Z",
    "DeletedAt": null,
    "SourceWallet": "",
    "Callback": "",
    "Subject": ""
}

The field PresentationSubmission includes the information the user shares, which in this case is only the email.

With this information, the user has been authenticated, which is used to authorize or not the user in the client service.

If you have any questions or need assistance integrating Gataca Studio, please get in touch with our support team at [e-mail] for further assistance.

---

Integrating the GatacaQR Component for Identity Wallet Interaction

To streamline the interaction with identity wallets, Gataca offers the GatacaQR component, a versatile JavaScript library designed for seamless session management. This component simplifies the integration process for relying parties, enabling them to generate and manage sessions effortlessly while enhancing user experience.

Key Features of GatacaQR

• QR Code Rendering: Displays a QR code that users can scan to initiate interactions with their identity wallet.

• Real-Time Communication: Supports features such as polling and WebSocket integration for efficient session updates.

• Deep Link Triggering: Allows for direct interaction with mobile devices via deep links, bypassing the need for QR scanning in certain use cases.

• Customizable Layout: Offers flexibility to adapt the appearance of the QR code and its surrounding elements to align with the relying party’s branding and design preferences.

• Ease of Integration: Simplifies complex session management workflows, providing a user-friendly API for developers.

Getting Started with GatacaQR

Developers can access comprehensive manuals and resources for using the GatacaQR component through the following repositories:

• NPM: @gataca/qr

• GitHub: Gataca-QR Repository

By leveraging GatacaQR, developers can focus on building intuitive user journeys while relying on a robust, pre-built solution for wallet interactions. This component ensures a streamlined, secure, and highly adaptable way to integrate identity wallet capabilities into your application.

---

WebHooks

The Gataca Studio platform introduces support for web-hooks, providing users with a flexible mechanism to receive real-time notifications about specific events within the system. Web-hooks can be configured directly through the graphical user interface (GUI), enabling seamless integration with external systems or workflows.

Verification Template

How Web-Hooks Work

1. Configuration: Users will define web-hooks via the Studio interface, specifying the target endpoint (URL). This functionality will be available for each of the templates that define the issuance and verification processes.

2. Triggering Events: When an event of interest occurs, Studio sends an HTTP POST request to the user-defined endpoint.

3. Payload: The POST request contains a structured payload with relevant data about the event. This allows external systems to process the information immediately and take appropriate actions.

Webhook Payload Structure

The payload sent to the configured endpoint will follow this format:

{
  "id": "017c9ece-6869-417a-8550-3f8ceee23199",
  "subject": "did:gatc:000000...000000",
  "status": "SUCCESS",
  "payload": {
    "email": "[e-mail]",
    ...
  },
  "verificationResult":{
      "checks":[
         "matchingIds",
         "presentationProof",
         "securityMechanisms",
         "credentialProof"
      ],
      "warnings":[
         "urn:uuid:YjQzNWI4ODI1NWQ4ZTY2YjI5MGE4NzU5 credential status not available."
      ],
      "errors":[]
   }
}

• id: Process identifier

• subject: Subject identifier

• status: Whole process status (SUCCESS, REJECT)

• payload: [OPTIONAL] Map with the claims shared by the subject (avoid including id). If there is no info into the credential subject this field won’t be included.

• verificationResult: List of results (steps passed, warnings and errors)

Benefits of Web-hook Integration

• Real-Time Updates: Enables immediate processing of events by external systems.

• Custom Workflows: Allows users to automate responses or actions based on Studio events.

• Scalability: Supports integration with diverse applications, including CRMs, analytics platforms, or custom systems.