Learn how to consume MATTR VII Webhooks

Overview

In an OpenID4VCI issuance workflow, you may want to trigger additional actions once a credential has been successfully issued. For example, sending a notification, updating a database, or invoking a downstream system.

MATTR VII Webhooks provide a simple way to achieve this by notifying consuming applications when specific events occur.

This tutorial will guide you through creating a webhook in your MATTR VII tenant and using a sample application to consume the webhook, verify the request, and display the event payload when a credential is issued. You can then adapt principles demonstrated in this tutorial to suit your specific use cases.

Tutorial overview

The current tutorial builds upon the Authorization Code or Pre-authorized Code tutorials by adding the following steps:

1. Create a MATTR VII Webhook: Configure MATTR VII to send a Webhook event when a credential is issued.
2. Set up a webhook receiver sample app: Use a sample Node.js application that achieves the following:
   • Exposes a public endpoint to receive Webhook events.
   • Verifies the authenticity of incoming requests using MATTR VII's public keys.
   • Logs the received event payload to the console.

Prerequisites

• Complete either the Authorization Code or Pre-authorized Code tutorials to configure a credential issuance flow.
• Node.js 18+ installed locally.
• To test locally you will need to expose your local consumer app to the internet. You can do this by setting up a free ngrok account, using a Cloudflare tunnel or using your own solution. For this tutorial we will be using ngrok. Sign up for a free account at ngrok.com.

Tutorial steps

POST /v1/webhooks

{
    "events": ["OpenIdCredentialIssued"],
    "url": "https://example.com"
}

{
    "id": "0c099611-19c4-4f29-8724-6b9e5ba1ef7c", 
    "events": ["OpenIdCredentialIssued"],
    "url": "https://example.com",
    "disabled": false //
}

npm install
npm run start

docker compose up --build

PUT /v1/webhooks/{id}

{
    "events": ["OpenIdCredentialIssued"],
    "url": "https://example.com"
}

What’s next?

Now that you have a working webhook consumer, you can extend the application to perform more meaningful actions based on the received events, as opposed to merely logging them. For example, you could:

• Store credential issuance events in a database.
• Trigger downstream APIs for automated workflows.

Production considerations

When moving your Webhooks usage into production, consider the following best practices:

• Secure your Webhook endpoint:

  • Require HTTPS at all times.
  • Use a firewall or allowlist to limit inbound traffic.
  • Validate that requests are signed with MATTR VII’s public keys (as shown in this tutorial).

• Make event processing idempotent:

  • MATTR VII does not guarantee that events arrive in order or only once.
  • Deduplicate by checking the event.id or deliveryId in the payload before processing.
  • Ensure that reprocessing the same event has no negative effect (e.g., sending duplicate emails, double-updating a record).

• Add monitoring and logging:

  • Capture request/response logs for debugging and auditing.
  • Monitor webhook failures, retries, and timeouts.
  • Consider alerting if repeated failures occur.