Learn

Webhooks

Overview

Webhooks on MATTR VII 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 MATTR VII 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 type is enabled on MATTR VII:

  • OidcIssuerCredentialIssued: This event is triggered at the completion of a credential being issued via the MATTR VII 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., OidcIssuerCredentialIssued

    • payload that contains any event specific data

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

json
Copy to clipboard. 
1{
2  "deliveryId": "9a8b0b72-5c4f-4925-b101-528edbb5d75d",
3  "deliveryTimestamp": "2022-08-30T01:26:38.325Z",
4  "webhookId": "5be4f663-af93-41d8-8542-f5c9a2a2d588",
5  "event": {
6    "id": "de347800-d56f-4262-9f19-52b34856a933",
7    "type": "OidcIssuerCredentialIssued",
8    "payload": {
9     ......
10    },
11    "timestamp": "2022-08-30T01:26:38.308Z"
12  }
13}

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

The event’s payload data object includes any event specific data.
Below is an example of what the data payload looks like for the OidcIssuerCredentialIssued event:

OidcIssuerCredentialIssued event data payload

json
Copy to clipboard. 
1"payload": 
2{
3  "issuerId": "64b6d5ec-3964-41b8-940f-223626bfa489",
4  "format": "w3cvc-jsonld",
5  "credential": {
6    "type": [
7      "VerifiableCredential",
8      "VerifiableCredentialExtension",
9      "EmailAddressCredential"
10    ],
11    "issuer": {
12      "id": "did:key:z6Mkk4uPewwDQanG8pqdogNa7x69tNwuhTdEzYC12ZYyrEnr",
13      "name": "prod vii.mattr.global"
14    },
15    "name": "Auth0 Email Credential",
16    "issuanceDate": "2022-08-30T01:26:37.693Z",
17    "credentialSubject": {
18      "id": "did:key:z6MkomnJ2Lfw1gGjd1oX3BWjRTVrBrihyqj7RiNc6W8Pr52S",
19      "email": "xxxxx@example.com",
20      "givenName": "John",
21      "familyName": "Smith"
22    },
23    "@context": [
24      "https://www.w3.org/2018/credentials/v1",
25      {
26        "@vocab": "https://w3id.org/security/undefinedTerm#"
27      },
28      "https://mattr.global/contexts/vc-extensions/v1",
29      "https://schema.org",
30      "https://w3id.org/vc-revocation-list-2020/v1"
31    ],
32    "credentialStatus": {
33      ...
34    },
35    "proof": {
36      ...
37    }
38  },
39  "oidcClaims": {
40    "given_name": "John",
41    "family_name": "Doe",
42    ....
43  }
44}

Steps

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