Webhooks
MATTR VII Webhooks enable retrieving information that is generated during an API interaction but is not included in the request or response payloads.
You can subscribe to specific events that are triggered on set MATTR VII operations to retrieve the required information whenever it is generated. When the subscribed event is triggered, the information relating to that event is published via the Webhook through to the URL(s) configured on the subscription.
The following MATTR VII event types can be subscribed to:
OpenIdCredentialIssued: Triggered upon completion of an OID4VCI workflow.OpenIdCredentialIssuedSummary: Triggered upon completion of an OID4VCI workflow but only provides a summary of the issuance event, leaving out thecredentialobject.OidcIssuerCredentialIssued: Triggered upon completion of an OIDC Bridge issuance flow.
A key use-case for these event payloads is to provide the DID that was used as the
credentialSubject.id when binding and issuing the credential to the subject’s wallet.
MATTR VII 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. You 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, make your event processing idempotent.
Webhook validation
To validate the integrity and authorship of Webhooks generated by the MATTR VII platform, all Webhook events are signed using HTTP Message Signatures (an IETF draft standard).
MATTR strongly encourages verifying each Webhook event to provide a suitable level of protection to integrations consuming the event information:
- Verify the HTTP signatures.
- Compare the
webhookIdidentifier that is generated when the Webhook is created to thewebhookIdspecified in the request.
Verifying HTTP signatures
You can obtain the public keys MATTR VII uses to sign the HTTP and use them to verify the HTTP signature. The response key set is relatively static and only expected to change on rare occasions, such as when performing key rotation.
To facilitate verification of MATTR VII Webhook requests, we provide a typescript-based library that can be used for verification or serve as a reference implementation to develop a verification SDK in another programming language.
An
open-source example
of using the @mattrglobal/http-signatures library is also available.
To learn more about verifying our Webhook requests, take a look at the Open Source MATTR Http-Signatures library.
Timeouts 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.