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

http
Copy to clipboard.
1POST https://YOUR_TENANT_SUBDOMAIN.vii.mattr.global/core/v1/webhooks
json
Copy to clipboard.
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:

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

json
Copy to clipboard.
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

http
Copy to clipboard.
1PUT https://YOUR_TENANT_SUBDOMAIN.vii.mattr.global/core/v1/webhooks/<WebhookID>
json
Copy to clipboard.
1{
2  "events": [
3    "OidcIssuerCredentialIssued"
4  ],
5  "url": "https://example.com",
6  "disabled": true
7}

Response

json
Copy to clipboard.
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.