Use a Webhook

Timeout and retry

When a Webhook fails to send data to the configured URL, or when a session timeout occurs, a maximum of three retry attempts are made at set intervals. The interval time increases exponentially according to the number of retries that have been attempted. If the webhook fails to send following the retry attempts, it will be marked as failed.

By default, the Webhook has a response timeout of three seconds. If the server receiving the Webhook event does not respond within this period it is considered a failure.

Event payload

The body of the event payload has a common structure in JSON format:

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": "OpenIdCredentialIssued",
8        "payload": { ... },
9        "timestamp": "2022-08-30T01:26:38.308Z"
10    }
11}
  • deliveryId: The unique identifier assigned each time the event is delivered to a Webhook endpoint.

  • deliveryTimestamp: The time when the event was delivered.

  • webhookId: The unique Webhook identifier returned in the response during its creation.

  • event: Includes the following event details:

    • id: Unique even identifier.

    • type: Event type (currently either OpenIdCredentialIssued or OidcIssuerCredentialIssued).

    • payload: Contains the specific event data.

    • timestamp: Specifies the date/time when the event was created.

When a Webhook event is sent from MATTR VII, x-mattr-webhook-id and x-mattr-event-type are added as request headers.

Event data

Below are examples of the data payload:

OpenIdCredentialIssued

Compact Credentials
json
Copy to clipboard.
1{
2  "format": "cwt",
3  "userId": "7382276d-ef75-4d17-8fb0-1d3aec4647ab",
4  "credentialProfile": "compact",
5  "credentialConfigurationId": "1d8c7ad7-84ce-4519-8365-7af986e4ee0e",
6  "credentialId": "9613ac5e-a0ba-4512-ba0b-90e91b2744bc",
7  "userClaims": {
8    "Name": "John"
9  },
10  "credential": "{base64url_encoded_credential}"
11}
Web Credentials
json
Copy to clipboard.
1{
2    "format": "ldp_vc",
3    "userId": "64a39a9d-c15b-4c78-9149-30f6376f1fbc",
4    "credentialProfile": "web-semantic",
5    "credentialConfigurationId": "bddb2a96-8b67-439a-b5af-2818bcfc716f",
6    "credential": {
7        "type": [
8            "VerifiableCredential",
9            "ExampleCredential"
10            ]
11        //... rest of credential data
12    }
13}
Mobile Credentials
json
Copy to clipboard.
1{
2    "format": "mso_mdoc",
3    "userId": "f21a2013-e535-46a8-af58-c39684bf730d",
4    "credentialProfile": "mobile",
5    "credentialConfigurationId": "97e712f9-90eb-4e3e-a134-156aacba45ff",
6    "credential": "{base64url_encoded_credential}"
7}

OidcIssuerCredentialIssued

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