Webhooks

This guide will demonstrate how to create or manage a webhook using MATTR VII.

Prerequisites

You need the following in order to proceed with this tutorial: 

• Access to the MATTR VII APIs

• A MATTR VII API flow set that utilises a webhook event type

If you’re experiencing any difficulties, contact us. 

Create a webhook

Request

1POST https://YOUR_TENANT_SUBDOMAIN.vii.mattr.global/core/v1/webhooks

1{
2  "events": [
3    "OidcIssuerCredentialIssued"
4  ],
5  "url": "https://example.com"
6}

The webhook event is triggered by the MATTR VII platform and allows users to subscribe to events that occur during supported MATTR VII operations.

The following webhook events are currently supported on MATTR VII:

• OidcIssuerCredentialIssued - This webhook event is triggered when a credential is issued via the MATTR VII OIDC bridge

The url attribute in the request payload above is the URL that you want to set up to receive the webhook events when they are triggered by MATTR VII for the specified events.

Any query parameters or hash fragments in the URL will be dropped, and non-ASCII characters will be normalised.

The url MUST be an HTTPS based URL.

The provided URL is expected to return a 2xx response, otherwise it will go through a retry cycle and eventually fail.

Response

1{
2  "id": "0c099611-19c4-4f29-8724-6b9e5ba1ef7c",
3  "events": [
4    "OidcIssuerCredentialIssued"
5  ],
6  "url": "https://example.com",
7  "disabled": false
8}

When a webhook is created, the disabled property is set to false by default.

If you need to create the webhook in an initial state of disabled, you can override the default by supplying "disabled":true in the request body.

When a webhook event is generated:

The MATTR VII platform does not guarantee the delivery of events in the exact order that they are generated or that no duplicate events will be received by the webhook endpoint.

MATTR VII users can safeguard against duplicates by checking the event.id that is provided in the event payload, this is a unique identifier for each event generated by MATTR VII. Alternatively, by making your event processing idempotent.

Disable a webhook

Existing webhooks can be disabled by updating the webhook.

When a webhook is disabled, notifications for the events associated with this webhook will be not sent.

Request

1PUT https://YOUR_TENANT_SUBDOMAIN.vii.mattr.global/core/v1/webhooks/<WebhookID>

1{
2  "events": [
3    "OidcIssuerCredentialIssued"
4  ],
5  "url": "https://example.com",
6  "disabled": true
7}

Response

1{
2  "id": "0c099611-19c4-4f29-8724-6b9e5ba1ef7c",
3  "events": [
4    "OidcIssuerCredentialIssued"
5  ],
6  "url": "https://example.com",
7  "disabled": true
8}

Timeout and retry

When a webhook fails to send data to the desired notification URL or a session timeout occurs,  a maximum of 3 retry attempts are made by MATTR VII 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 MATTR VII webhook service has a response timeout of 3 seconds. This means if the server receiving the webhook event does not respond within this period it is considered a failure.