Webhooks

Overview

Webhooks on Sovrin API allow users to obtain information that is generated during an API operation that isn't otherwise available as part of the request or response payloads.

Users are able to subscribe to specific events that are triggered on set Sovrin API operations.

When an event is triggered, the information relating to that event is published via the webhook through to the URL(s) set up on the configured subscription(s).

The following event types are enabled on Sovrin API:

• OpenIdCredentialIssued: This event is triggered at the completion of a credential being issued using OpenID Credential Provisioning flow.

• OidcIssuerCredentialIssued: This event is triggered at the completion of a credential being issued via the Sovrin API OIDC Bridge .

A key use of this event's payload is to provide the user with the DID that was used as the credentialSubject.id when binding and issuing the credential to the subject's wallet.

Event data

The body of the event payload has a common structure, in JSON format. This includes:

• deliveryId – The unique identifier assigned each time the event is delivered to a webhook endpoint.

• deliveryTimestamp – The time when the notification was delivered

• webhookId – The ID of the webhook that is returned in the response during its creation

• event

• id that is used to uniquely identify the event

• type of the event, i.e., OpenIdCredentialIssued or OidcIssuerCredentialIssued

• payload that contains any event specific data

• timestamp that specifies the date/time for when the event was created

{
    "deliveryId": "9a8b0b72-5c4f-4925-b101-528edbb5d75d",
    "deliveryTimestamp": "2022-08-30T01:26:38.325Z",
    "webhookId": "5be4f663-af93-41d8-8542-f5c9a2a2d588",
    "event": {
        "id": "de347800-d56f-4262-9f19-52b34856a933",
        "type": "OpenIdCredentialIssued",
        "payload": { ... },
        "timestamp": "2022-08-30T01:26:38.308Z"
    }
}

tip

As part of the process, when a webhook event is raised from the Sovrin API platform, x-sovrin-webhook-id and x-sovrin-event-type are added in as request headers.

The event’s payload data object includes any event specific data. Below are the examples of what the data payload structure is for the OpenIdCredentialIssued and OidcIssuerCredentialIssued events:

OpenIdCredentialIssued event data payload

{
    "format": "ldp_vc",
    "userId": "64a39a9d-c15b-4c78-9149-30f6376f1fbc",
    "credentialProfile": "web-semantic",
    "credentialConfigurationId": "bddb2a96-8b67-439a-b5af-2818bcfc716f",
    "credential": {
        "type": [
            "VerifiableCredential",
            "ExampleCredential"
        ],
        "issuer": {
            "id": "did:web:organization.com",
            "name": "Tenant.organization.com"
        },
        "name": "Auth0 Email Credential",
        "description": "This is an example credential",
        "issuanceDate": "2022-08-30T01:26:37.693Z",
        "credentialSubject": {
            "id": "did:key:z6MkomnJ2Lfw1gGjd1oX3BWjRTVrBrihyqj7RiNc6W8Pr52S",
            "email": "xxxxx@example.com",
            "givenName": "John",
            "familyName": "Smith"
        },
        "@context": [
            "https://www.w3.org/2018/credentials/v1",
            "https://w3id.org/vc-revocation-list-2020/v1",
            "https://sovrin.network/contexts/vc-extensions/v2",
            "https://schema.org"
        ],
        "credentialStatus": { ... },
        "proof": { ... }
    }
}

OidcIssuerCredentialIssued event data payload

{
    "issuerId": "64b6d5ec-3964-41b8-940f-223626bfa489",
    "format": "w3cvc-jsonld",
    "credential": {
        "type": [
            "VerifiableCredential",
            "VerifiableCredentialExtension",
            "EmailAddressCredential"
        ],
        "issuer": {
            "id": "did:web:organization.com",
            "name": "Tenant.organization.com"
        },
        "name": "Auth0 Email Credential",
        "issuanceDate": "2022-08-30T01:26:37.693Z",
        "credentialSubject": {
            "id": "did:key:z6MkomnJ2Lfw1gGjd1oX3BWjRTVrBrihyqj7RiNc6W8Pr52S",
            "email": "xxxxx@example.com",
            "givenName": "John",
            "familyName": "Smith"
        },
        "@context": [
            "https://www.w3.org/2018/credentials/v1",
            {
                "@vocab": "https://w3id.org/security/undefinedTerm#"
            },
            "https://sovrin.network/contexts/vc-extensions/v1",
            "https://schema.org",
            "https://w3id.org/vc-revocation-list-2020/v1"
        ],
        "credentialStatus": { ... },
        "proof": { ... }
    },
    "oidcClaims": {
        "given_name": "John",
        "family_name": "Doe",
        ...
    }
}

Steps

Follow the guide to understand the standard steps required to create and manage webhooks.

• Create a Webhook

• Verify a Webhook