Verifying a webhook

To allow MATTR VII users 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 MATTR VII users to verify each webhook event to provide a suitable level of protection to integrations consuming the event information. One way of doing this is to verify the HTTP signatures.

MATTR VII users should also compare the webhookId that is generated at the creation of the webhook to the webhookId specified in the request.

Using HTTP-Signature Library

MATTR VII users can obtain the public keys from this endpoint.

Users can obtain the public keys MATTR VII uses to sign the HTTP request from this endpoint, these can be used to verify the HTTP signature.
The response key set is relatively static and only expected to change on rare occasions, such as performing key rotation.
Users should use the kid specified in the JWK key object to identify which key a particular HTTP request is signed with, as the key set can change or contain multiple keys.

Request

1GET https://YOUR_TENANT_SUBDOMAIN.vii.mattr.global/v1/webhooks/jwks

Response

1{
2  "keys": [
3    {
4      "kty": "OKP",
5      "crv": "Ed25519",
6      "kid": "1608085995",
7      "x": "1NYsB58B9bNmReXqyQR8R_DeJtoLHSW-JsyZVmV2EWQ"
8    }
9  ]
10}

In order to facilitate customers verifying webhook requests from the MATTR VII platform, we provide a typescript based library that can be used for verification purposes or serve as a reference implementation to develop a verification SDK in another programming language.

Access our NPM library here.

An open-source example of using the @mattrglobal/http-signatures library is also available.

Access the Sample App here.

To learn more about verifying our webhook requests, have a look at the Open Source MATTR Http-Signatures library here.